@nocobase/app-skills 0.1.0-beta.39 → 0.1.0-beta.40
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/package.json +2 -2
- package/skills/nocobase-app-development/SKILL.md +12 -11
- package/skills/nocobase-app-development/references/app-structure.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/api.md +4 -2
- package/skills/nocobase-app-development/references/frontend/references/page.md +2 -2
- package/skills/nocobase-app-upgrade/SKILL.md +4 -0
- package/skills/nocobase-app-upgrade/references/edge-cases.md +13 -1
- package/skills/nocobase-app-upgrade/references/realtime-upgrade.md +61 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nocobase/app-skills",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.40",
|
|
4
4
|
"description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"devDependencies": {
|
|
19
19
|
"@playwright/test": "^1.62.1",
|
|
20
20
|
"prettier": "^3.9.6",
|
|
21
|
-
"@nocobase/dev-config": "0.1.0-beta.
|
|
21
|
+
"@nocobase/dev-config": "0.1.0-beta.24"
|
|
22
22
|
},
|
|
23
23
|
"peerDependencies": {
|
|
24
24
|
"@playwright/test": "^1.62.1",
|
|
@@ -41,16 +41,17 @@ Build the feature in the application. Do not run a plugin generator, create a `p
|
|
|
41
41
|
|
|
42
42
|
NocoBase packages may publish Skills under `.agents/skills/`. Current application templates run `pnpm nocobase skills sync` automatically through `postinstall`; run it manually if install scripts were disabled or that directory is missing or stale. Confirm that the package is a direct `@nocobase/*` dependency or a registered plugin before relying on its Skill. The common capability mappings are:
|
|
43
43
|
|
|
44
|
-
| The requirement sounds like
|
|
45
|
-
|
|
|
46
|
-
| Email, IM, or in-app messages
|
|
47
|
-
| Roles, permissions, per-user or per-record access
|
|
48
|
-
| Sign-in, registration, sessions
|
|
49
|
-
| File upload and metadata through Repository
|
|
50
|
-
| File storage, disk configuration, or custom drivers
|
|
51
|
-
| Translated text and language switching
|
|
52
|
-
| User administration and application-owned role assignment
|
|
53
|
-
|
|
|
44
|
+
| The requirement sounds like | Read the Skill for |
|
|
45
|
+
| -------------------------------------------------------------- | ------------------------------------------ |
|
|
46
|
+
| Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
|
|
47
|
+
| Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
|
|
48
|
+
| Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
|
|
49
|
+
| File upload and metadata through Repository | `@nocobase/app-plugin-file` |
|
|
50
|
+
| File storage, disk configuration, or custom drivers | `@nocobase/drive` |
|
|
51
|
+
| Translated text and language switching | `@nocobase/app-plugin-i18n` |
|
|
52
|
+
| User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
|
|
53
|
+
| Live updates, snapshot recovery and replacing business polling | `@nocobase/realtime` (`nocobase-realtime`) |
|
|
54
|
+
| Reading or writing data, schema changes, migrations | `@nocobase/db` |
|
|
54
55
|
|
|
55
56
|
Read the relevant Skill before writing the feature, but treat this table as a map rather than an installed-package list. Implementing a permission system, a notification sender, or a scheduler by hand when a registered plugin provides one is the most expensive mistake available here.
|
|
56
57
|
|
|
@@ -194,7 +195,7 @@ These cause real damage and appear in every reference:
|
|
|
194
195
|
- **Let the owning page supply `PageContainer`.** One per page; inline child pages and tabs use the parent's, covering child pages add their own, overlays use their own container. See [section 2 of pages and routes](references/frontend/references/page.md#2-the-page-component).
|
|
195
196
|
- **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
|
|
196
197
|
- **Route paths never include the deployment base path.** The runtime restores it.
|
|
197
|
-
- **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts
|
|
198
|
+
- **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts`; pages load data with `useApiClient` (see [calling the API](references/frontend/references/api.md)).
|
|
198
199
|
- **Reach for the built-in mechanism first.** Changing framework structure is allowed when nothing else fits — comment it and record it in `.agents/rules/`.
|
|
199
200
|
- **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
|
|
200
201
|
- **Remove direct NocoBase packages with `package remove` after reviewing their usage.** Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
|
|
@@ -51,7 +51,7 @@ Configure storage in `server/config/drive.ts`, with serializable overrides in `c
|
|
|
51
51
|
|
|
52
52
|
`client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the `package.json` scripts that call `nocobase`, and the tsconfigs are the scaffolding the template provides. It is still this application's own source — it shipped to the user and they may change it — but it is the part the template evolves, so an edit there is what a future upgrade has to reconcile. [Customizing the shell](frontend/references/shell.md) lists the shell behaviors to keep.
|
|
53
53
|
|
|
54
|
-
Prefer the mechanism the system already provides. Declare a page in `client/routes.ts` and add `navigation` when it needs a menu entry
|
|
54
|
+
Prefer the mechanism the system already provides. Declare a page in `client/routes.ts` and add `navigation` when it needs a menu entry; pages load data through `useApiClient`. A page uses `authz` to restrict access; a plugin page is customized through an option or an override. Before editing the shell to add a menu, check the route and its `navigation` declaration.
|
|
55
55
|
|
|
56
56
|
When the built-in mechanism genuinely cannot express what is being asked, changing this structure is a legitimate answer — not a last resort to apologize for. Do it deliberately, and leave the next agent enough to work with:
|
|
57
57
|
|
|
@@ -230,9 +230,11 @@ export async function uploadProjectAttachment(
|
|
|
230
230
|
|
|
231
231
|
## Loading data in a component
|
|
232
232
|
|
|
233
|
-
|
|
233
|
+
For live updates, read the installed `nocobase-realtime` Skill in `.agents/skills/` for server authorization, snapshot recovery, retries, distributed delivery and polling decisions.
|
|
234
234
|
|
|
235
|
-
|
|
235
|
+
Data reloads when the user acts (a search, "Retry", a refresh button) or after the page's own writes. For live updates, declare the server Topic during provider boot and reuse the host client through `useRealtimeTopic` or `useRealtimeRefresh` from `@nocobase/app-client`. A watch's `onReady` runs after that Topic is acknowledged, including reconnects; `onOpen` only describes the transport. Refresh authoritative API data on readiness because disconnected events are not replayed. Use `enabled: false` for inactive pages, return the refresh promise for burst coalescing and one in-flight follow-up, and use `refreshRealtimeQueries(queryClient, filters, signal)` for TanStack Query snapshots. It matches exact keys, prefixes and predicates, waits for pre-event reads (including initial loading), and follows them with a fresh read without repeatedly cancelling slow requests. Bare `invalidateQueries` with `cancelRefetch: false` can reuse a pre-event response and lose the change. For lower-level code, resolve `realtimeClientToken` and call `watch(topic, { onEvent, onReady, onError })`; close its handle on cleanup. Personal inbox usage is documented in the `nocobase-app-plugin-notification-in-app` Skill.
|
|
236
|
+
|
|
237
|
+
There is no shared data-loading hook; write it directly in the component: `useApiClient()` + `useEffect` + `AbortController`. Do not reach for TanStack Query in a page: one loading pattern across pages keeps states and errors consistent. The component below loads a project by id and displays it, covering loading, retry after failure, record not found, no permission and empty values (`client/pages/projects/project-summary.tsx`):
|
|
236
238
|
|
|
237
239
|
```tsx
|
|
238
240
|
// client/pages/projects/project-summary.tsx (excerpt; the complete file is in example/project-summary.md)
|
|
@@ -278,7 +278,7 @@ Write `navigation` on the route. The application sidebar reads its menu entries
|
|
|
278
278
|
- Pages that should not appear in the menu (details, tab content and so on) have no `navigation`. When such a page is open, the menu highlights the nearest ancestor that has a menu entry.
|
|
279
279
|
- **A path with a parameter (`:projectId`) cannot have `navigation`**; registration raises an error, because a menu entry must point to a fixed URL (wildcards are rejected on every route, [section 1](#1-declare-the-route)).
|
|
280
280
|
- Navigation group: write only `name`, `navigation` and `children`, without `componentLoader`. For groups and clickable parents, see [`child-routes.md`](child-routes.md).
|
|
281
|
-
- Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry
|
|
281
|
+
- Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry; the home page entry is declared in the routes as well.
|
|
282
282
|
- A new page with a menu entry usually touches four places: `client/routes.ts`, the page component, `client/locales/` and, for an App page that requires sign-in, the page grant list in `tests/logic/client-routes.test.ts` ([section 12](#12-update-the-route-test)).
|
|
283
283
|
|
|
284
284
|
### A count beside an entry
|
|
@@ -403,7 +403,7 @@ export function ExportProjectsButton({
|
|
|
403
403
|
- Use it for page permissions too, for example for an entry on the home page that points to a page: `useCan({ resource: { type: 'page', id: 'projects' }, action: 'access' })`. A route's `authz` uses the same `{ resource: { type, id }, action }`.
|
|
404
404
|
- **`useCan` answers "does this user have this feature", not "can this record be acted on"**. For actions that depend on record state or data scope, the server returns the actions available for each record in the list or detail response, and the UI shows them accordingly; the endpoint checks again when it executes.
|
|
405
405
|
- Hide actions the user has no permission for; disable actions that are temporarily unavailable and explain why in a tooltip (guideline I7).
|
|
406
|
-
- In a component, get the authorization client with `useAuthorizationClient()`; outside React, resolve `authorizationClientToken` from the application container and call `client.can({ resource, action })`. When state you maintain yourself must reload after permissions change, use `useAuthorizationRevision()`. Do not use
|
|
406
|
+
- In a component, get the authorization client with `useAuthorizationClient()`; outside React, resolve `authorizationClientToken` from the application container and call `client.can({ resource, action })`. When state you maintain yourself must reload after permissions change, use `useAuthorizationRevision()`. Do not use a global authorization client, and do not store permission results in module-level variables (they linger after switching accounts).
|
|
407
407
|
- **Hiding something in the UI does not replace endpoint authorization.**
|
|
408
408
|
- When the business has different job responsibilities, data scopes or field permissions, read the `nocobase-app-plugin-authorization` Skill first, then design the pages, business actions and record scopes.
|
|
409
409
|
|
|
@@ -96,6 +96,8 @@ diff -rq "$WORK/$BASE" "$WORK/$TARGET"
|
|
|
96
96
|
|
|
97
97
|
When the upgrade changes application migrations or registered plugins that supply migrations, read [database upgrades](references/database-upgrades.md) during planning, before starting the target application. Review the affected packages' upgrade notes as well as the template diff: a dependency update can change database behavior without adding a migration file to the application. Include any documented checksum correction, data prerequisite, and irreversible migration in the upgrade and recovery plan. A Git branch protects source, not the database.
|
|
98
98
|
|
|
99
|
+
When BASE → TARGET changes Realtime contracts, read [Realtime upgrades](references/realtime-upgrade.md) during planning and include application-owned consumers, custom plugins, workers and transport/test adapters in step 5. Topic authorization, ignored publication promises and recovery gaps can survive type checking; use the actual package contracts and project usage to decide which migration steps apply.
|
|
100
|
+
|
|
99
101
|
Then ask the project which of those files it has also touched:
|
|
100
102
|
|
|
101
103
|
```bash
|
|
@@ -159,6 +161,8 @@ pnpm typecheck && pnpm test && pnpm lint && pnpm build
|
|
|
159
161
|
|
|
160
162
|
`typecheck` is doing real work here — it catches the broken import a removal left behind. Before starting the application against retained data, complete the applicable [database upgrade checks](references/database-upgrades.md); startup may apply migrations automatically. Then run the application and check what the delta touched: sign-in, the user's pages, navigation, locale switching, any new migration. Passing commands are not evidence the application still behaves. For a theme or shell change, also complete the [theme upgrade checks](references/theme-upgrade.md); token changes alone do not verify the application-owned consumers.
|
|
161
163
|
|
|
164
|
+
For a Realtime contract change, complete the applicable [Realtime acceptance checks](references/realtime-upgrade.md#verify-the-migrated-application), including access denial, reconnect catch-up and publication failure; a connected socket alone is insufficient evidence.
|
|
165
|
+
|
|
162
166
|
Report the range merged, how each contested file was decided, any manual actions and their validation, and how to roll back.
|
|
163
167
|
|
|
164
168
|
## Crossing several releases
|
|
@@ -170,7 +170,7 @@ Legacy application-owned guidance, when present
|
|
|
170
170
|
|
|
171
171
|
An application from before `@nocobase/app-cli` took over the whole command line depends on `@nocobase/nb3-cli` and, usually, `@nocobase/app-tools`. Neither is published any more, so the upgrade has to move to the new layout in one step; there is no compatibility period.
|
|
172
172
|
|
|
173
|
-
1. In `package.json`, remove `@nocobase/nb3-cli` and `@nocobase/app-tools`, keep `@nocobase/app-cli` in `dependencies` at the target template's range, and add the development tools it expects the application to provide to `devDependencies` — `typescript`, `tsx`, `vite`, `prettier`, `tar`,
|
|
173
|
+
1. In `package.json`, remove `@nocobase/nb3-cli` and `@nocobase/app-tools`, keep `@nocobase/app-cli` in `dependencies` at the target template's range, and add the development tools it expects the application to provide to `devDependencies` — `typescript`, `tsx`, `vite`, `prettier`, `tar`, `tsc-alias` and `@nocobase/dev-config`, taking the target template's ranges.
|
|
174
174
|
2. Replace `scripts` with the target template's: `postinstall`, `dev`, `build` and `start` run `nocobase …`, and the quality scripts stay. Delete the command aliases (`config:*`, `db:*`, `migrate`, `seed`, `collections:generate`, `plugin:*`, `package:remove`, `skills:sync`, `upload`, `deploy`, `server:deps:*`, `nocobase`); each is now `pnpm nocobase <topic> <command>`. Keep scripts the user added that are not aliases, and ask before dropping one they redefined.
|
|
175
175
|
3. If the application published to a Hub (it had `upload` and `deploy`), those commands have no replacement; see [Hub publishing](#hub-publishing).
|
|
176
176
|
4. Delete `scripts/dev.mjs`, `scripts/build.mjs`, `scripts/start.mjs` and `scripts/server-deps.mjs`, and `cli/index.ts`. Compare any locally modified script first and move application-specific behavior into a plugin build or dev hook.
|
|
@@ -221,6 +221,18 @@ The release that stops shipping `DataTable` and `DatePicker` shows their files a
|
|
|
221
221
|
1. Search the application for imports of each file and primitive and of each package before removing any of them, as [step 5](../SKILL.md#5-check-what-the-diff-cannot-show) describes. A file something still imports stays as application-owned code, together with the primitives and packages it needs; nothing about it has to change. Remove only what nothing imports.
|
|
222
222
|
2. Keep the `dataTable` and `datePicker` keys in the locale files; the target template keeps them.
|
|
223
223
|
|
|
224
|
+
## Refine removed from the client runtime
|
|
225
|
+
|
|
226
|
+
The release in which `@nocobase/app-client` 4 drops Refine removes `app.refine`, `app.refineConfig`, `runWithProviderContext`, `runWithProviderContextAsync` and the `AppClientRefine*` types, `@nocobase/i18n/client` drops `createRefineI18nProvider` and its types, and `@nocobase/app-plugin-repository-example` drops its `./client/providers` export. The application shell no longer mounts `<Refine>`; `AppClientProviders` creates the TanStack Query cache Refine used to create, in the same place, so pages and plugins that call `useQuery` or `useQueryClient()` keep working without a provider of their own. `nocobase build` runs `vite build` for the client where it ran `refine build`. Every application generated before this release carries a call the new types reject, so `pnpm typecheck`, and with it `pnpm build`, fails until it is removed.
|
|
227
|
+
|
|
228
|
+
Make these changes together, before the [Finish step](../SKILL.md#8-finish) installs dependencies:
|
|
229
|
+
|
|
230
|
+
1. In `client/service-provider.ts`, delete `this.app.refine.setOptions({ title: { text: title } })`; the `document.title` lines beside it are what set the title and stay. An application from the Examples template also deletes the `this.app.refine.addResources([...])` call. `grep -rn "app\.refine\|refineConfig\|AppClientRefine\|runWithProviderContext\|RefineI18nProvider\|repository-example/client/providers" client/ tests/` lists any other call: a resource, option or provider set this way was never read by anything but Refine, so the call goes without a replacement. A test asserting `app.refineConfig.options?.title` asserts `document.title` instead, as the target's `tests/components/app-title.test.tsx` does.
|
|
231
|
+
2. In `package.json`, remove `@refinedev/cli`, `@refinedev/core`, `@refinedev/react-hook-form`, `@refinedev/react-router` and `@refinedev/react-table` from `devDependencies`, and take the target's range for `@tanstack/react-query`. Remove `<Refine>` from any test fixture that wraps a component in it, such as `tests/fixtures/theme-tokens.tsx`.
|
|
232
|
+
3. Search for imports from `@refinedev/` in `client/` before removing the packages. An application that adopted Refine's data hooks with a data provider of its own keeps those packages and mounts `<Refine>` itself in an `application`-layer entry of `client/react-providers.ts`, passing what the old shell passed: its data provider, `routerProvider` from `@refinedev/react-router`, and `options={{ syncWithLocation: true, disableTelemetry: true }}`. Refine's data hooks call TanStack Query's hooks, which read the nearest `QueryClientProvider`, so when a page calls them they use the cache around the routes, as they did before. Refine's own `authProvider` invalidates the cache Refine creates for itself, which pages do not read. Resolve a single copy of `@tanstack/react-query`, since the hooks of a second copy read another context and find no cache. An application that relied on Refine's translations also passes an `i18nProvider` of its own, because `createRefineI18nProvider` is no longer exported from `@nocobase/i18n/client`.
|
|
233
|
+
|
|
234
|
+
After the Finish step, run `pnpm typecheck`, `pnpm test` and `pnpm build`, then open a page that loads data and, when the application has one, the inbox.
|
|
235
|
+
|
|
224
236
|
## Hub publishing
|
|
225
237
|
|
|
226
238
|
NocoBase Hub is discontinued, and with it `@nocobase/hub-cli` and the `pnpm nocobase hub` commands. An application that depends on `@nocobase/hub-cli`, sets `"nocobase": { "cli": { "publishing": true } }`, or runs `release upload`, `release deploy`, `hub upload` or `hub deploy` in CI or scripts published to a Hub. An application with none of these needs none of the steps below.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Realtime upgrades
|
|
2
|
+
|
|
3
|
+
## Decide which changes apply
|
|
4
|
+
|
|
5
|
+
Use this reference when BASE → TARGET changes the Realtime contracts used by the application or its plugins. The declared-topic contract was introduced on the `@nocobase/app-server` 3.0.0 prerelease line: undeclared topics are rejected, server publication and subscription authorization are asynchronous, and publication returns an event receipt. Check the actual BASE and TARGET declarations and release notes; the application may already have adopted these contracts. Do not infer compatibility from the template version or require every `@nocobase/*` package to share the same major version.
|
|
6
|
+
|
|
7
|
+
Resolve the compatible package set from the target template, including `@nocobase/app-server`, `@nocobase/app-client`, `@nocobase/realtime`, the WebSocket adapter and affected plugins. Before installation, inspect `skills/nocobase-realtime/SKILL.md` and its references in the exact target `@nocobase/realtime` tarball, together with its README and `docs/distributed.md`. After installation and `pnpm nocobase skills sync`, use `.agents/skills/nocobase-realtime/SKILL.md` when available. A currently installed Skill can describe BASE; do not treat it as the authority for TARGET or edit synchronized copies. The target declarations govern exact signatures and options.
|
|
8
|
+
|
|
9
|
+
Apply only the differences the application still needs. A patch that fixes refresh internals without changing a consumed contract needs no source migration. This API migration does not itself require a database change; review any separate plugin migrations through the upgrade Skill's database workflow.
|
|
10
|
+
|
|
11
|
+
## Inventory application-owned consumers
|
|
12
|
+
|
|
13
|
+
Search the application's source and custom plugin/worker repositories, including test helpers and transport adapters. This initial search finds service imports, declarations, publication-result assumptions, readiness listeners and polling consumers; follow aliases and wrappers from the hits rather than treating a zero-result search as proof of compatibility:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
rg -n '(@nocobase/(realtime|app-server/realtime)|realtimeServiceToken|realtimeClientToken|useRealtime|refreshRealtimeQueries|createRealtimeRefresh|defineTopic|registerTopic|subscriberCount|subscriptionCount|onTopicSubscriptionChange|onOpen|onReady|refetchInterval|setInterval)' . --glob '*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}' --glob '!node_modules/**' --glob '!dist/**' --glob '!pnpm-lock.yaml'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
For each consumer, identify the topic and its declaration owner, publisher, audience/resource policy, authoritative snapshot or persisted cursor, and recovery path. Follow publication wrappers through transactions, jobs and failure handlers. Include owned packages outside this directory; report inaccessible external plugin code as an unverified compatibility dependency. Put required adaptations and any unresolved access policy in the upgrade plan before editing.
|
|
20
|
+
|
|
21
|
+
## Migrate server contracts
|
|
22
|
+
|
|
23
|
+
| Existing assumption or use | Required adaptation when the target changes this contract |
|
|
24
|
+
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
25
|
+
| Any valid topic string can be published or subscribed to | Declare static topics with `defineTopic`/`registerTopic` and dynamic resource families with `defineTopicFamily` during provider boot, before subscriptions. Keep a single declaration owner and release its handles at shutdown. Validate existing dynamic IDs against the target's topic format. |
|
|
26
|
+
| A topic name or signed-in socket proves resource access | Preserve the intended audience. A user topic derives its subscriber from the authenticated principal; a resource family reuses the snapshot endpoint's access policy before subscription and delivery. `audience: 'public'` alone does not require authentication or resource permission. Do not remove restrictions to make a migrated subscription succeed. |
|
|
27
|
+
| Server operations finish synchronously | Await server `publish`, topic `publish`/`publishFor`, `subscribe`, `handleClientMessage`, `disconnectUser` and service `close` where owned; update adapters and mocks accordingly. Await `disconnectSession` if used. Host applications retain `realtimeServiceToken` from `@nocobase/app-server/realtime`; the host owns service setup/shutdown. Standalone services own `setup()` and `close()`. Topic-handle `close()` and browser subscription cleanup remain synchronous. |
|
|
28
|
+
| A surrounding synchronous `try/catch` handles announcement failure | Await publication inside the handler or attach an explicit rejection handler. Publish after the transaction commits. A best-effort announcement failure must not turn an already committed write into a failed HTTP response or cause the business write to repeat. Use the domain's durable outbox/job when retries are required. |
|
|
29
|
+
| `publish()` returns `{ topic, subscriberCount }` or proves delivery | Consume `{ eventId, topic }` for tracing. The promise means broker admission, not browser processing. Local subscription counts and `flush()` cannot prove remote delivery; remove local-subscriber guards that suppress cross-process publication. Use persisted revisions/cursors for business ordering and gap recovery. |
|
|
30
|
+
| Payloads are accepted whenever `JSON.stringify` succeeds | Send finite, acyclic JSON with plain objects and dense arrays. Convert dates to ISO strings and domain objects to explicit data; reject or deliberately map `undefined`, non-finite numbers, functions, accessors, symbols and unsupported objects. Test representative payloads against target validation and size limits even with no subscribers. |
|
|
31
|
+
|
|
32
|
+
For concrete declarations, transaction boundaries and adapter options, follow the target Realtime Skill's server reference. Do not replace the host service with another instance merely because its implementation moved to `@nocobase/realtime/server`.
|
|
33
|
+
|
|
34
|
+
## Migrate browser recovery and test doubles
|
|
35
|
+
|
|
36
|
+
`subscribe(topic, listener)` still returns a cleanup function. Keep it where event-only consumption is sufficient; use `watch` or the host hooks when a consumer needs acknowledged readiness or per-topic errors. Read an authoritative snapshot after each topic's `onReady`, including the first subscription and reconnect. Keep `onOpen` for transport/identity work. Reconnect on sign-in, sign-out or session replacement, and clear account-bound caches; a replacement account must not reuse the former account's socket or data.
|
|
37
|
+
|
|
38
|
+
For query-backed pages, use the target's `refreshRealtimeQueries` with `useRealtimeRefresh` or `createRealtimeRefresh` where appropriate. Return the actual refresh promise so reads started before an event receive a follow-up read and failures remain observable. Preserve a usable snapshot during transient failures, clear protected data after HTTP 401/403, and keep subscription errors separate from snapshot errors. The query helper clears denied query snapshots; direct state readers must clear their own protected data and guard late responses.
|
|
39
|
+
|
|
40
|
+
When adopting the refresh scheduler, wire the existing Refresh/Try again action to its `retry()`. Retry exhaustion is not reset by another event. Topic readiness and manual retry can start a new attempt; foreground/online recovery applies to transient failures. Preserve failed work when batching later events. Follow the target Realtime Skill's client reference for retry options and cleanup rather than duplicating the scheduler in application code.
|
|
41
|
+
|
|
42
|
+
Update test doubles to return publication promises and correlate subscription acknowledgements/errors and heartbeat replies with their request IDs. An open fake socket without acknowledgements no longer proves subscription readiness. Test publication admission separately from delivery; `flush()` can wait for local queues in tests, while remote delivery needs an observed recipient.
|
|
43
|
+
|
|
44
|
+
## Preserve recovery during rollout
|
|
45
|
+
|
|
46
|
+
Keep recovery polling until all relevant producers announce changes and disconnected clients can reconcile from durable data. External changes, time-based expiry and failed best-effort announcements may still require a suitable reconciliation interval. Replacing every poll is not a prerequisite for this upgrade.
|
|
47
|
+
|
|
48
|
+
The default memory broker is local to one service. For an existing multi-process deployment, verify the target adapter and application namespace across web processes and workers; a shared namespace alone does not distribute events. If Redis fan-out is used, follow the target package's distributed guide and verify broker recovery. Pub/Sub supplies no replay. During a mixed-version rollout, old browsers may not understand `resync`; retain periodic reconciliation or arrange a client reload, and verify the actual client/server combination instead of assuming wire compatibility.
|
|
49
|
+
|
|
50
|
+
## Verify the migrated application
|
|
51
|
+
|
|
52
|
+
Run the upgrade Skill's package checks, then exercise affected application behavior. Select the cases that match the migrated consumers and record skipped or unavailable scenarios explicitly:
|
|
53
|
+
|
|
54
|
+
- **Declarations and access:** Known topics receive updates for authorized users; undeclared topics, anonymous callers to authenticated topics and unauthorized resource subscriptions are denied. Revoking resource access stops subsequent delivery. Existing grants and private payload boundaries remain intact.
|
|
55
|
+
- **Committed writes:** A rolled-back transaction announces no change. A successful write still succeeds when best-effort publication rejects, with the failure handled and recovery available. Valid production payloads pass, invalid or oversized payloads fail without unhandled rejections, including with zero subscribers.
|
|
56
|
+
- **Readiness and catch-up:** Change data while a client is disconnected, reconnect, and verify its snapshot after acknowledged readiness without requiring another mutation. Deliver an event while an earlier read is pending and verify that the final UI reflects the newer data.
|
|
57
|
+
- **Failure recovery:** A transient snapshot error recovers without a new event. After automatic retries are exhausted, the existing manual action recovers without restarting the business job. HTTP 401/403 stops automatic retries and clears protected snapshots; subscription refusal is reported separately.
|
|
58
|
+
- **Identity and cleanup:** Sign out and sign in as another account; neither old events nor cached private data appear. Navigating away releases watches/timers, and late reads cannot overwrite the new page or account.
|
|
59
|
+
- **Distributed use, when applicable:** A worker with no local subscribers reaches a browser on another process. Separate application namespaces remain isolated. After broker recovery, current clients reauthorize and catch up; the rollout's old-client fallback also recovers. Record which topology was actually exercised.
|
|
60
|
+
|
|
61
|
+
Report the contracts changed, custom consumers migrated, applicable checks and remaining compatibility gaps alongside the template version range and rollback plan. Type checking or a healthy WebSocket alone does not establish upgrade success.
|