@ahoo-wang/wow-view-store 9.8.0 → 10.0.0-alpha.3

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 (37) hide show
  1. package/README.md +115 -137
  2. package/README.zh-CN.md +89 -100
  3. package/dist/datasetWordings.d.ts +47 -0
  4. package/dist/index.d.ts +1 -0
  5. package/dist/index.es.js +188 -257
  6. package/dist/index.es.js.map +1 -1
  7. package/dist/paths.d.ts +2 -0
  8. package/dist/remembered.d.ts +9 -0
  9. package/dist/remembered.es.js +147 -0
  10. package/dist/remembered.es.js.map +1 -0
  11. package/dist/v10/datasetWordings.d.ts +46 -0
  12. package/dist/v10/errors.d.ts +83 -0
  13. package/dist/v10/generated/index.d.ts +1 -0
  14. package/dist/v10/generated/view-store/boundedContext.d.ts +36 -0
  15. package/dist/v10/generated/view-store/dataset_wording/aggregate.d.ts +17 -0
  16. package/dist/v10/generated/view-store/dataset_wording/commandClient.d.ts +32 -0
  17. package/dist/v10/generated/view-store/dataset_wording/index.d.ts +3 -0
  18. package/dist/v10/generated/view-store/dataset_wording/queryClient.d.ts +18 -0
  19. package/dist/v10/generated/view-store/index.d.ts +5 -0
  20. package/dist/v10/generated/view-store/types.d.ts +167 -0
  21. package/dist/v10/generated/view-store/view/aggregate.d.ts +17 -0
  22. package/dist/v10/generated/view-store/view/commandClient.d.ts +65 -0
  23. package/dist/v10/generated/view-store/view/index.d.ts +3 -0
  24. package/dist/v10/generated/view-store/view/queryClient.d.ts +18 -0
  25. package/dist/v10/generated/view-store/view_preferences/aggregate.d.ts +17 -0
  26. package/dist/v10/generated/view-store/view_preferences/commandClient.d.ts +22 -0
  27. package/dist/v10/generated/view-store/view_preferences/index.d.ts +3 -0
  28. package/dist/v10/generated/view-store/view_preferences/queryClient.d.ts +18 -0
  29. package/dist/v10/index.d.ts +6 -0
  30. package/dist/v10/source.d.ts +46 -0
  31. package/dist/v10/systemViews.d.ts +21 -0
  32. package/dist/v10/wire.d.ts +25 -0
  33. package/dist/v10/wowViewStore.d.ts +179 -0
  34. package/dist/v10.es.js +673 -0
  35. package/dist/v10.es.js.map +1 -0
  36. package/dist/wowViewStore.d.ts +13 -0
  37. package/package.json +12 -6
package/README.md CHANGED
@@ -8,7 +8,7 @@ of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md), kept by the
8
8
  standalone `wow-view-store-server` or by any Wow service that embeds
9
9
  `wow-view-store-starter`.
10
10
 
11
- Released with Wow 9.2.0, from the same tag and with the same version, together
11
+ Released with Wow, from the same tag and with the same version, together
12
12
  with the view engine and the view store's server modules.
13
13
 
14
14
  > **Compatibility.** From 9.2.0 on, a patch release never breaks the public
@@ -72,149 +72,125 @@ one all need it. Left out, everything is allowed — but the engine's
72
72
  off unless the host's answer says `true`: give it by the role the gateway
73
73
  admits to `tenant/(platform)/owner/(system)` (`view-store/README.md`, 「System views」).
74
74
 
75
- ### A host nobody signs in to
75
+ ### Dataset wording
76
76
 
77
- Without a token, nothing fills the path's tenant and owner. Such a host adds an
78
- interceptor of its own that fills defaults where the request gives none, and
79
- names its application; with the owner `(shared)` (`SHARED_OWNER_ID`) it has
80
- shared views and shared preferences only, so its permissions leave
81
- `createPersonal` off.
77
+ `WowDatasetWordings` keeps a tenant's wording over its datasets (the view
78
+ engine's dataset overrides: title, record noun, field labels, order and
79
+ narrowing) under `owner/(shared)`, one per dataset and application, keyed by
80
+ the dataset's definition id. Hand it to the datasets as their store of
81
+ wording: `DatasetResources` reads it before each refresh, registers each
82
+ dataset in its stored words, and gives the view manager its wording tab
83
+ where the host grants `editDatasetWording`:
82
84
 
83
- <!-- typecheck-context
84
- import { Fetcher } from '@ahoo-wang/fetcher';
85
+ ```ts
86
+ import type { Fetcher } from '@ahoo-wang/fetcher';
87
+ import {
88
+ DatasetDirectoryClient,
89
+ DatasetQueryClient,
90
+ } from '@ahoo-wang/wow-client';
91
+ import { DatasetResources, type ViewEngine } from '@ahoo-wang/wow-view-engine';
92
+ import { WowDatasetWordings } from '@ahoo-wang/wow-view-store';
93
+
94
+ declare const engine: ViewEngine;
85
95
  declare const fetcher: Fetcher;
96
+
97
+ const directory = new DatasetDirectoryClient();
98
+ const datasets = new DatasetResources(engine, {
99
+ list: () => directory.list(),
100
+ source: entry =>
101
+ new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
102
+ wordings: new WowDatasetWordings({ fetcher }),
103
+ });
104
+ await datasets.refresh();
105
+ ```
106
+
107
+ `set(dataset, wording, revision, { requestId })` writes one whole at the
108
+ expected revision (`'0'` for one never written) and `clear` removes it; the
109
+ gateway decides who may, by the role it admits to
110
+ `…/owner/(shared)/datasets/{dataset}/wording`.
111
+
112
+ ### On a Wow V10 service
113
+
114
+ `@ahoo-wang/wow-view-store/v10` is the same port on the **V10** view store
115
+ service (`platform/view-store` in the Wow repository): `WowViewStore` and
116
+ `WowDatasetWordings` of the same names and options, built on the clients
117
+ generated from the service's Manifest (`@ahoo-wang/wow-client/v10`), and
118
+ `viewSourceOf` / `datasetCatalogOf`, which put the engine's queries on V10
119
+ query routes. The root entry stays the 9.x store; a host picks one by the
120
+ entry it imports.
121
+
122
+ <!-- typecheck-context
123
+ import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
124
+ declare const orders: ViewDefinition;
125
+ declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
86
126
  -->
87
127
 
88
128
  ```ts
89
- import type { FetchExchange, RequestInterceptor } from '@ahoo-wang/fetcher';
90
- import { SHARED_OWNER_ID } from '@ahoo-wang/wow-view-store';
91
-
92
- class ConsoleDefaults implements RequestInterceptor {
93
- readonly name = 'ConsoleDefaults';
94
- readonly order = 0;
95
-
96
- intercept(exchange: FetchExchange): void {
97
- const path = exchange.ensureRequestUrlParams().path;
98
- path.tenantId ??= '(0)';
99
- path.ownerId ??= SHARED_OWNER_ID;
100
- exchange.ensureRequestHeaders()['CoSec-App-Id'] = 'console';
101
- }
102
- }
103
-
104
- fetcher.interceptors.request.use(new ConsoleDefaults());
129
+ import { Fetcher } from '@ahoo-wang/fetcher';
130
+ import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client/v10';
131
+ import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
132
+ import {
133
+ WowDatasetWordings,
134
+ WowViewStore,
135
+ datasetCatalogOf,
136
+ viewSourceOf,
137
+ } from '@ahoo-wang/wow-view-store/v10';
138
+
139
+ // The V10 service takes the tenant and the owner from the principal: the
140
+ // fetcher's interceptors send the authorization and `CoSec-App-Id`, and no
141
+ // path names either.
142
+ const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
143
+
144
+ const engine = new ViewEngine({
145
+ store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
146
+ resources: [
147
+ {
148
+ definition: orders,
149
+ // Any V10 query route: a generated `…SnapshotQueryClient` fits too.
150
+ source: viewSourceOf(
151
+ new SnapshotQueryClient(
152
+ { context: 'sales', name: 'order' },
153
+ { fetcher },
154
+ ),
155
+ ),
156
+ },
157
+ ],
158
+ });
159
+
160
+ // The service's datasets (`GET /wow/dataset`), worded by the tenant.
161
+ const datasets = new DatasetResources(engine, {
162
+ ...datasetCatalogOf(new DatasetClient({ fetcher })),
163
+ wordings: new WowDatasetWordings({ fetcher }),
164
+ });
165
+ await datasets.refresh();
105
166
  ```
106
167
 
107
- ## How it maps the port
108
-
109
- Every route is under `/view-store/tenant/{tenantId}/owner/{ownerId}`, and **the
110
- owner segment is the audience**: a personal view lives on the caller's own path,
111
- a shared one on `owner/(shared)`.
112
-
113
- | Port | Request |
114
- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115
- | `list` | The snapshot list on the caller's path and on `(shared)`, projected to the summary (`state.config.kind`, not the config), and `GET (shared)/system-views?definitionId=`, sent together |
116
- | `get` | The snapshot of one id where the view was last seen; an unknown id is looked up on the caller's path, then `(shared)`, then the system views |
117
- | `create` | `POST …/view` on the path of its `scope` (`system`: `tenant/(platform)/owner/(system)`); the server generates the id |
118
- | `save`, `rename`, `delete` | `PUT …/view/{id}/save`, `/rename`, `DELETE …/view/{id}` on the view's path |
119
- | `changeAudience('shared')` | `PUT …/view/{id}/share` on the view's path |
120
- | `changeAudience('personal')` | `PUT …/view/{id}/claim` on the caller's own path |
121
- | `getPreferences`, `setPreferences` | `GET`, `PUT …/definitions/{definitionId}/preferences` on the caller's path |
122
-
123
- A list answers in the port's order — the system views, then the shared views,
124
- then the caller's, each audience oldest first (the server sorts it by
125
- `firstEventTime`) — and reads at most 1,000 views of each audience, the server's
126
- query budget: the oldest 1,000. A view past the cut is still read by its id, and
127
- the workbench asks for one an address names before it sets it aside.
128
-
129
- **Writes** send the port's `requestId` as `Command-Request-Id`, the `revision`
130
- as `Command-Aggregate-Version` (`'0'` for preferences never written), and wait
131
- for the snapshot. The answer is the view read back at the version the write
132
- left. `share` and `delete` send `{}`, `claim` no body.
133
-
134
- **A retry answers the first outcome.** A write the server refuses as a stale
135
- version or a repeated request id is looked up by its request id first
136
- (`GET …/view/requests/{requestId}`, on the path it was sent to and then the
137
- other one): if the first attempt landed, its outcome is the answer. Only then is
138
- a stale version `CONFLICT`, carrying the view as it is now — or `NOT_FOUND`,
139
- when the view is gone. A lookup the server fails is no answer: on the path the
140
- write went to, the outcome is unknown (`UNAVAILABLE`, and a retry is safe); on the
141
- other path — `(shared)` refuses a caller without the shared role — the write is
142
- taken as not replayed, and the refusal stands. A write that landed and was moved
143
- on by another writer before the read back answers the view as the replay route
144
- gives it, or, if that route cannot be asked, as it was read. Preferences have no such route: the store answers a retry
145
- with what its own first attempt answered, and a retry whose first answer was
146
- lost with what is stored, when that is what it wrote.
147
-
148
- **Creating is not idempotent on the server**, which generates the id. The store
149
- remembers the request ids of its own creates (the last 256), and a retry of one
150
- first asks the replay route on the path of its `scope`: if the first attempt
151
- landed, that view is the answer, and nothing is posted again. A retry from
152
- another store instance — another tab, a reload — makes a second view.
153
-
154
- **A view that moved.** When another tab shared a view this store remembers as
155
- personal (or the other way round), the write is refused on the old path; the
156
- store looks the view up again and sends the write once more to where it is.
157
-
158
- **System views.** The server's system views (`GET (shared)/system-views`) are
159
- configured ones, read-only, and stored ones (`source: 'stored'`), which
160
- `WowViewStore` lists and reads with `stored: true` on the summary and the
161
- instance. A stored one is written on `tenant/(platform)/owner/(system)`
162
- (`SYSTEM_TENANT_ID`, `SYSTEM_OWNER_ID`) whatever the caller's tenant: they are
163
- global. `create({ scope: 'system', … })` publishes one (a copy: the source
164
- view stays), `save`, `rename` and `delete` edit and unpublish it;
165
- `changeAudience` and any write to a configured or code system view are
166
- `FORBIDDEN` before anything is sent.
167
-
168
- A system view's `revision` is a hash of its content, as the engine needs for
169
- its dirty baseline, while a write expects the aggregate version: the store
170
- remembers the `version` each read of a stored view gave beside its revision,
171
- sends that version, and when the engine holds a revision it has no version
172
- for, reads the view again first — a revision other than the view's is
173
- `CONFLICT` with the view as it is, and nothing is sent. The answer of a write
174
- is read back from the system-views route at the version it left. A retry the
175
- server refuses as a repeated request is found by the replay route on the
176
- system path, but that route answers a snapshot, whose content hash only the
177
- server computes: the store answers it with the system view **as it is now**,
178
- which is the retried write's outcome unless another admin wrote in between.
179
- A retry whose first attempt moved the view on (so the revision it holds is no
180
- longer the view's) asks the replay route before it is refused as `CONFLICT`,
181
- and a retried create of a system view answers the view from the system
182
- views, flagged and at its hash.
183
-
184
- ## Errors
185
-
186
- Every rejection is the engine's `ViewStoreError`, read by Wow's error code — the
187
- HTTP status only when an answer carries no code the store knows:
188
-
189
- | Server | Port |
190
- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
191
- | `CommandExpectVersionConflict`, `EventVersionConflict`, `SourcingVersionConflict`; without a known code, 409 and 412 | `CONFLICT` |
192
- | `NotFound` (also a view of another application), `IllegalAccessDeletedAggregate`; without a known code, 404 and 410 | `NOT_FOUND` |
193
- | `IllegalAccessOwnerAggregate`, `IllegalAccessSpaceAggregate`, `IllegalAccessQueryScope`, `SystemViewReadOnly`, `ViewEventStreamClosed`; without a known code, 401 and 403 | `FORBIDDEN` |
194
- | `ViewInvalid`, `ViewAppRequired`, `ViewScopeRequired`, `BadRequest`, `CommandValidation`, `IllegalArgument`, `DuplicateAggregateId`, `QuerySchemaValidation`; without a known code, 400 and 422; a path variable the fetcher's interceptors never filled (nothing is sent) | `INVALID` |
195
- | `IllegalState`, `RequestTimeout`, `TooManyRequests`, `InternalServerError`, `QuerySchemaUnavailable`, `QuerySchemaConflict`; without a known code, any other status; no answer at all | `UNAVAILABLE` |
196
- | `404` from a server with no view store at all (one released before it): a list, or a read whose every place is `404` while the server's system views are too | `UNSUPPORTED` |
197
-
198
- Every `ViewStoreError` keeps what it was read from: the request's failure as
199
- `cause`, the server's `errorCode` as `detail.code` (so a host tells
200
- `ViewAppRequired` from `ViewInvalid`, both `INVALID`), and on an `UNAVAILABLE`
201
- the server answered — a 5xx, a timeout it reported, a page that is not JSON —
202
- `reachable: true`, which the engine says as 「服务端暂时无法处理」 rather than
203
- 「无法连接服务端」.
204
-
205
- A repeated request id (`DuplicateRequestId`) is not an error of its own: the
206
- store looks the first attempt up (above). A path variable left unfilled is the
207
- host's set-up — its interceptors do not fill `{tenantId}`, or `{ownerId}` on a
208
- personal path — so it is `INVALID`, as the server's own `ViewScopeRequired` is:
209
- the request is wrong as built, and a retry would send it the same.
210
-
211
- A claim the server refuses because shared dashboards show the view carries those
212
- boards' **titles** in the error's `boards`, as stored, and the view engine says
213
- the refusal in its own words around them: a title written as a key stays a key,
214
- said where the refusal is shown. The `message` keeps the server's words, for
215
- logs.
216
-
217
- `WowViewStoreErrorCodes` names the view store's own codes.
168
+ What differs from the 9.x store is the service's, not the port's:
169
+
170
+ - **Who is asking** comes from the principal; a shared view is written as
171
+ the reserved owner `(shared)` and a stored system view as `(system)` of
172
+ `(platform)`, which the store says itself with `Wow-Scope`. The service
173
+ authorizes each write: give `createShared` and `changeAudience` by the role
174
+ that writes `(shared)` (`view-store.shared-writer` as shipped), and
175
+ `editSystem` by the one that writes `(system)`.
176
+ - **Writes** carry the port's request id as `Wow-Request-Id` and its revision
177
+ as `If-Match`; the service deduplicates every write by its request id,
178
+ creates included, so a retry from any tab is answered with the first
179
+ outcome. Setting a view shared or personal waits for the service's saga
180
+ that moves it to its new owner.
181
+ - **Errors** are read by the problem's `code`: a `ViewStoreError` carries it
182
+ as `detail.code` (`WowViewStoreErrorCodes` lists the view store's own), and
183
+ a route the service does not serve (`404` without a code) is `UNSUPPORTED`.
184
+ - **A page's total** is the service's default `BOUNDED` count: a V10 service
185
+ refuses an exact total over HTTP.
186
+
187
+ ## Documentation
188
+
189
+ | To | Read |
190
+ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
191
+ | Choose where views live, wire `WowViewStore`, give permissions, serve a host nobody signs in to | [Where views live](https://wow.ahoo.me/guide/typescript/view-engine-storage#wowviewstore-views-on-a-wow-service) |
192
+ | The exports, the contract, every request the port sends and how server errors map to the port | [wow-view-store reference](https://wow.ahoo.me/reference/typescript/wow-view-store/) |
193
+ | Run the view store server, its configuration and the gateway rules | [View store](https://wow.ahoo.me/guide/extensions/view-store) |
218
194
 
219
195
  ## Testing
220
196
 
@@ -222,6 +198,8 @@ logs.
222
198
  server, the public surface and the API report.
223
199
  - The port's conformance suite runs over `WowViewStore` against a view store
224
200
  server in `typescript/integration-test` (`test/view-store/`), with the tenant
225
- and application isolation.
201
+ and application isolation; over the V10 `WowViewStore` against the V10 view
202
+ store service, which `pnpm --dir typescript/integration-test test:v10`
203
+ starts on ports bound to 0 (`test/view-store-v10/`).
226
204
 
227
205
  Licensed under the Apache License, Version 2.0.
package/README.zh-CN.md CHANGED
@@ -6,7 +6,7 @@
6
6
  保存的视图与偏好,由[视图存储](../../view-store/README.md)保管——两个 Wow 聚合,由独立的
7
7
  `wow-view-store-server` 提供,或由任何引入了 `wow-view-store-starter` 的 Wow 服务提供。
8
8
 
9
- 随 Wow 9.2.0 发布,与 Wow 同一个 tag、同一个版本号,与视图引擎和视图存储的服务端模块一起发布。
9
+ 随 Wow 发布,与 Wow 同一个 tag、同一个版本号,与视图引擎和视图存储的服务端模块一起发布。
10
10
 
11
11
  > **兼容性。** 从 9.2.0 起,补丁版本不破坏公开面(入口的导出与错误码);次版本可以破坏,它的发布说明
12
12
  > 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上,见[版本范围](https://wow.ahoo.me/zh/guide/typescript/compatibility#版本范围)。
@@ -58,117 +58,106 @@ const engine = new ViewEngine({
58
58
  但引擎的 `editSystem`(发布、编辑、取消发布存储的系统视图)只在宿主明确答 `true` 时打开:按网关放行
59
59
  `tenant/(platform)/owner/(system)` 的角色给(`view-store/README.md`「System views」)。
60
60
 
61
- ### 不登录的宿主
61
+ ### 数据集措辞
62
62
 
63
- 没有令牌,就没有谁去填路径里的租户与所有者。这样的宿主加一个自己的拦截器,在请求没给时填上缺省值,并说明自己
64
- 是哪个应用;所有者填 `(shared)`(`SHARED_OWNER_ID`)时,它只有共享视图与共享偏好,所以它的权限把
65
- `createPersonal` 关掉。
63
+ `WowDatasetWordings` 在 `owner/(shared)` 下存租户给数据集写的措辞(视图引擎的数据集覆盖:标题、名词、字段的
64
+ 口径、次序与收窄),每个应用、每个数据集一份,按数据集的定义 id 存。把它交给数据集作措辞存储:`DatasetResources`
65
+ 每次刷新前读它,按存着的措辞登记每个数据集,并在宿主给了 `editDatasetWording` 时给视图管理器一个「措辞」页签:
66
66
 
67
- <!-- typecheck-context
68
- import { Fetcher } from '@ahoo-wang/fetcher';
67
+ ```ts
68
+ import type { Fetcher } from '@ahoo-wang/fetcher';
69
+ import {
70
+ DatasetDirectoryClient,
71
+ DatasetQueryClient,
72
+ } from '@ahoo-wang/wow-client';
73
+ import { DatasetResources, type ViewEngine } from '@ahoo-wang/wow-view-engine';
74
+ import { WowDatasetWordings } from '@ahoo-wang/wow-view-store';
75
+
76
+ declare const engine: ViewEngine;
69
77
  declare const fetcher: Fetcher;
78
+
79
+ const directory = new DatasetDirectoryClient();
80
+ const datasets = new DatasetResources(engine, {
81
+ list: () => directory.list(),
82
+ source: entry =>
83
+ new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
84
+ wordings: new WowDatasetWordings({ fetcher }),
85
+ });
86
+ await datasets.refresh();
87
+ ```
88
+
89
+ `set(dataset, wording, revision, { requestId })` 按期望版本整份写入(从没写过的是 `'0'`),`clear` 清掉;谁能写由网关
90
+ 按放行 `…/owner/(shared)/datasets/{dataset}/wording` 的角色决定。
91
+
92
+ ### 在 Wow V10 服务上
93
+
94
+ `@ahoo-wang/wow-view-store/v10` 是同一个端口在 **V10** 视图存储服务(Wow 仓库的 `platform/view-store`)上的实现:同名、同选项的 `WowViewStore` 与 `WowDatasetWordings`,建在由服务的 Manifest 生成的客户端(`@ahoo-wang/wow-client/v10`)之上;`viewSourceOf`/`datasetCatalogOf` 把引擎的查询放到 V10 的查询路由上。根入口仍是 9.x 的 store,宿主按导入的入口二选一。
95
+
96
+ <!-- typecheck-context
97
+ import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
98
+ declare const orders: ViewDefinition;
99
+ declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
70
100
  -->
71
101
 
72
102
  ```ts
73
- import type { FetchExchange, RequestInterceptor } from '@ahoo-wang/fetcher';
74
- import { SHARED_OWNER_ID } from '@ahoo-wang/wow-view-store';
75
-
76
- class ConsoleDefaults implements RequestInterceptor {
77
- readonly name = 'ConsoleDefaults';
78
- readonly order = 0;
79
-
80
- intercept(exchange: FetchExchange): void {
81
- const path = exchange.ensureRequestUrlParams().path;
82
- path.tenantId ??= '(0)';
83
- path.ownerId ??= SHARED_OWNER_ID;
84
- exchange.ensureRequestHeaders()['CoSec-App-Id'] = 'console';
85
- }
86
- }
87
-
88
- fetcher.interceptors.request.use(new ConsoleDefaults());
103
+ import { Fetcher } from '@ahoo-wang/fetcher';
104
+ import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client/v10';
105
+ import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
106
+ import {
107
+ WowDatasetWordings,
108
+ WowViewStore,
109
+ datasetCatalogOf,
110
+ viewSourceOf,
111
+ } from '@ahoo-wang/wow-view-store/v10';
112
+
113
+ // V10 服务从主体取租户与所有者:fetcher 的拦截器带上认证与 `CoSec-App-Id`,
114
+ // 路径里不出现两者。
115
+ const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
116
+
117
+ const engine = new ViewEngine({
118
+ store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
119
+ resources: [
120
+ {
121
+ definition: orders,
122
+ // 任意 V10 查询路由;生成的 `…SnapshotQueryClient` 同样可以。
123
+ source: viewSourceOf(
124
+ new SnapshotQueryClient(
125
+ { context: 'sales', name: 'order' },
126
+ { fetcher },
127
+ ),
128
+ ),
129
+ },
130
+ ],
131
+ });
132
+
133
+ // 服务的数据集(`GET /wow/dataset`),措辞由租户自己定。
134
+ const datasets = new DatasetResources(engine, {
135
+ ...datasetCatalogOf(new DatasetClient({ fetcher })),
136
+ wordings: new WowDatasetWordings({ fetcher }),
137
+ });
138
+ await datasets.refresh();
89
139
  ```
90
140
 
91
- ## 端口怎样落到请求上
92
-
93
- 所有路由都在 `/view-store/tenant/{tenantId}/owner/{ownerId}` 之下,**所有者段就是受众**:个人视图在调用者
94
- 自己的路径上,共享视图在 `owner/(shared)` 上。
95
-
96
- | 端口 | 请求 |
97
- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
- | `list` | 调用者路径与 `(shared)` 上的快照列表,只投影摘要的字段(`state.config.kind`,不含配置),以及 `GET (shared)/system-views?definitionId=`,三个请求一起发 |
99
- | `get` | 在上次见到这个视图的地方按 id 读快照;没见过的 id 依次在调用者路径、`(shared)`、系统视图上找 |
100
- | `create` | 在其 `scope` 对应的路径上 `POST …/view`(`system`:`tenant/(platform)/owner/(system)`);id 由服务端生成 |
101
- | `save`、`rename`、`delete` | 在视图所在路径上 `PUT …/view/{id}/save`、`/rename`,`DELETE …/view/{id}` |
102
- | `changeAudience('shared')` | 在视图所在路径上 `PUT …/view/{id}/share` |
103
- | `changeAudience('personal')` | 在调用者自己的路径上 `PUT …/view/{id}/claim` |
104
- | `getPreferences`、`setPreferences` | 调用者路径上的 `GET`、`PUT …/definitions/{definitionId}/preferences` |
105
-
106
- 列表按端口规定的顺序作答——系统视图、共享视图、调用者的个人视图,每种受众按创建先后(服务端按 `firstEventTime`
107
- 排序)——每种受众最多读 1000 个,即服务端的查询上限:最早的 1000 个。截断之外的视图仍可按 id 读到,地址里点名的
108
- 视图工作台会先按 id 问一次,再决定是不是别的定义的。
109
-
110
- **写入**把端口的 `requestId` 作为 `Command-Request-Id`、`revision` 作为 `Command-Aggregate-Version`
111
- (从没写过的偏好是 `'0'`)发送,并等到快照落地。作答的是按这次写入留下的版本读回的视图。`share` 与 `delete`
112
- 发送 `{}`,`claim` 不带请求体。
113
-
114
- **重试答第一次的结果。** 服务端以过期版本或重复的请求 id 拒绝一次写入时,先按请求 id 查一次
115
- (`GET …/view/requests/{requestId}`,先在这次发往的路径上,再在另一条上):第一次已经落地,就以它的结果作答。
116
- 之后过期版本才是 `CONFLICT`,带上视图现在的样子——视图已经不在了则是 `NOT_FOUND`。服务端答不上来的查询不算回答:
117
- 在这次发往的路径上,结局未知(`UNAVAILABLE`,重试安全);在另一条路径上——没有共享角色的调用者在 `(shared)`
118
- 会被拒——就当没有重放,原来的拒绝照旧。已经落地、读回前又被别人推过的写入,以重放路由给的那一版作答;
119
- 那条路由问不了时,以读回的作答。偏好没有这样的路由:
120
- store 以自己第一次得到的结果回答重试;第一次的回答丢了的重试,在存着的正是它写的内容时,以存着的作答。
121
-
122
- **创建在服务端不是幂等的**,id 由服务端生成。store 记着自己发出的创建的请求 id(最近 256 个),
123
- 重试其中一个时先在其 `scope` 的路径上问重放路由:第一次已经落地,就以那个视图作答,不再发一次。
124
- 从另一个 store 实例发出的重试——另一个标签页、刷新之后——会再建一个视图。
125
-
126
- **挪了地方的视图。** 另一个标签页把这个 store 记作个人的视图设为了共享(或反过来),写入在旧路径上被拒;
127
- store 重新找到视图,把写入再发一次到它现在所在的地方。
128
-
129
- **系统视图。** 服务端的系统视图(`GET (shared)/system-views`)有配置的,只读;也有存储的(`source: 'stored'`),
130
- `WowViewStore` 列出、读取它们时在摘要与实例上带 `stored: true`。存储的系统视图是全局的,不管调用者在哪个租户,
131
- 都写在 `tenant/(platform)/owner/(system)`(`SYSTEM_TENANT_ID`、`SYSTEM_OWNER_ID`)上。`create({ scope: 'system', … })`
132
- 发布一个(是复制,源视图不变),`save`、`rename`、`delete` 编辑与取消发布;`changeAudience`,以及对配置的或
133
- 代码声明的系统视图的任何写入,都在发出请求之前就是 `FORBIDDEN`。
134
-
135
- 系统视图的 `revision` 是内容的散列,引擎的「已改动」基线靠它;而写入要的是聚合版本:store 记着每次读到的存储视图
136
- 在那个 revision 上的 `version`,写入时发这个版本;引擎拿着一个 store 没有版本的 revision 时,先重读一次——
137
- 与视图当前不符的 revision 是 `CONFLICT`,带上视图现在的样子,什么都不发。写入的答复按它留下的版本从系统视图路由
138
- 读回。服务端以重复请求拒绝的重试,会在系统路径上的重放路由里找到,但那条路由答的是快照,内容散列只有服务端算得出:
139
- store 以系统视图**现在的样子**作答——除非这期间另一位管理员写过,那就是这次重试的结果。第一次已经把视图推过、手里的 revision 已不是视图当前的那个的重试,
140
- 先问重放路由,再以 `CONFLICT` 拒绝;重试的系统视图创建,从系统视图路由读回作答,带标记、用内容散列。
141
-
142
- ## 错误
143
-
144
- 所有拒绝都是引擎的 `ViewStoreError`,按 Wow 的错误码读——只有回答里没有 store 认得的错误码时才看 HTTP 状态:
145
-
146
- | 服务端 | 端口 |
147
- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
148
- | `CommandExpectVersionConflict`、`EventVersionConflict`、`SourcingVersionConflict`;没有认得的错误码时 409、412 | `CONFLICT` |
149
- | `NotFound`(别的应用的视图也是)、`IllegalAccessDeletedAggregate`;没有认得的错误码时 404、410 | `NOT_FOUND` |
150
- | `IllegalAccessOwnerAggregate`、`IllegalAccessSpaceAggregate`、`IllegalAccessQueryScope`、`SystemViewReadOnly`、`ViewEventStreamClosed`;没有认得的错误码时 401、403 | `FORBIDDEN` |
151
- | `ViewInvalid`、`ViewAppRequired`、`ViewScopeRequired`、`BadRequest`、`CommandValidation`、`IllegalArgument`、`DuplicateAggregateId`、`QuerySchemaValidation`;没有认得的错误码时 400、422;fetcher 的拦截器没填的路径变量(什么都没发) | `INVALID` |
152
- | `IllegalState`、`RequestTimeout`、`TooManyRequests`、`InternalServerError`、`QuerySchemaUnavailable`、`QuerySchemaConflict`;没有认得的错误码时其余状态;根本没有回答 | `UNAVAILABLE` |
153
- | 没有视图存储的服务端(早于它发布的)答的 `404`:列表,或每处都 `404` 且服务端的系统视图也 `404` 的读写 | `UNSUPPORTED` |
154
-
155
- 每个 `ViewStoreError` 都留着它的来处:请求本身的失败是 `cause`,服务端的 `errorCode` 是 `detail.code`(宿主据此分辨同为
156
- `INVALID` 的 `ViewAppRequired` 与 `ViewInvalid`);服务端答了话的 `UNAVAILABLE`——5xx、它报的超时、不是 JSON 的页面——带
157
- `reachable: true`,引擎据此说「服务端暂时无法处理」,而不是「无法连接服务端」。
158
-
159
- 重复的请求 id(`DuplicateRequestId`)本身不是错误:store 去查第一次的结果(见上)。没填的路径变量是宿主的配置问题——
160
- 拦截器没填 `{tenantId}`,或个人路径上的 `{ownerId}`——所以与服务端自己的 `ViewScopeRequired` 一样是 `INVALID`:
161
- 请求一构造就是错的,重试发出的还是同一个。
162
-
163
- 服务端因为有共享仪表盘显示着视图而拒绝收为个人时,错误的 `boards` 原样带上那几块看板的**标题**,由视图引擎用自己的话
164
- 说出这次拒绝:以键写的标题仍是键,在显示拒绝的地方说成话。`message` 保留服务端的原话,供日志。
165
-
166
- `WowViewStoreErrorCodes` 列出视图存储自己的错误码。
141
+ 与 9.x 的 store 不同的是服务端,不是端口:
142
+
143
+ - **谁在问**取自主体;共享视图以保留所有者 `(shared)` 写入,存储的系统视图以 `(platform)` 的 `(system)` 写入,由 store 自己用 `Wow-Scope` 说明。每次写入由服务端鉴权:按写 `(shared)` 的角色(出厂为 `view-store.shared-writer`)给 `createShared` 与 `changeAudience`,按写 `(system)` 的角色给 `editSystem`。
144
+ - **写入**把端口的请求 id 作为 `Wow-Request-Id`、revision 作为 `If-Match` 发出;服务端按请求 id 对每次写入去重(创建也是),所以任何标签页的重试都答第一次的结果。设为共享/设为个人会等服务端把视图移到新所有者的 saga。
145
+ - **错误**按 problem 的 `code` 读:`ViewStoreError` 把它放在 `detail.code`(视图存储自己的码见 `WowViewStoreErrorCodes`),服务端不提供的路由(不带码的 `404`)是 `UNSUPPORTED`。
146
+ - **一页的总数**是服务端缺省的 `BOUNDED` 计数:V10 服务不允许经 HTTP 要精确总数。
147
+
148
+ ## 文档
149
+
150
+ | 想做的事 | 读 |
151
+ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
152
+ | 选择视图放在哪里、接入 `WowViewStore`、给出权限、服务不登录的宿主 | [视图存放在哪里](https://wow.ahoo.me/zh/guide/typescript/view-engine-storage#wowviewstore-视图存在-wow-服务上) |
153
+ | 导出、合同、端口发出的每个请求,以及服务端错误怎样映射到端口 | [wow-view-store 参考](https://wow.ahoo.me/zh/reference/typescript/wow-view-store/) |
154
+ | 运行视图存储服务端、它的配置与网关规则 | [视图存储](https://wow.ahoo.me/zh/guide/extensions/view-store) |
167
155
 
168
156
  ## 测试
169
157
 
170
158
  - `pnpm --filter @ahoo-wang/wow-view-store test`——对着假服务端的单元测试、公开面与 API 报告。
171
159
  - 端口的一致性测试套件在 `typescript/integration-test`(`test/view-store/`)里对着视图存储服务端跑
172
- `WowViewStore`,另有租户与应用的隔离测试。
160
+ `WowViewStore`,另有租户与应用的隔离测试;V10 的 `WowViewStore` 对着 V10 视图存储服务跑,
161
+ `pnpm --dir typescript/integration-test test:v10` 把服务起在绑定 0 的端口上(`test/view-store-v10/`)。
173
162
 
174
163
  以 Apache License 2.0 许可。
@@ -0,0 +1,47 @@
1
+ import { Fetcher } from '@ahoo-wang/fetcher';
2
+ import { DatasetOverrides, DatasetWordingStore, StoredDatasetWording, WriteContext } from '@ahoo-wang/wow-view-engine';
3
+ /** How a {@link WowDatasetWordings} reaches the view store: as a `WowViewStore` does. */
4
+ export interface WowDatasetWordingsOptions {
5
+ /**
6
+ * The fetcher every request goes through, as {@link WowViewStoreOptions.fetcher}:
7
+ * its interceptors fill `{tenantId}` and send `CoSec-App-Id`. The
8
+ * wording is the tenant's, so the store always names the owner `(shared)`.
9
+ */
10
+ fetcher: Fetcher;
11
+ }
12
+ /**
13
+ * The wording a tenant's administrators keep over its datasets in the Wow
14
+ * view store (view engine D86): one per dataset of the caller's tenant and
15
+ * application, under `owner/(shared)`. The gateway decides who may write it.
16
+ *
17
+ * A host hands it to the datasets it registers as their store of wording
18
+ * (`DatasetCatalog.wordings`, D91): `DatasetResources` reads it before each
19
+ * refresh, registers each dataset in its stored words, and gives the view
20
+ * manager an editor of them. The key is the dataset's definition id,
21
+ * `{context}.{dataset}`.
22
+ *
23
+ * ```ts
24
+ * const resources = new DatasetResources(engine, {
25
+ * list: () => directory.list(),
26
+ * source: entry => directory.source(entry),
27
+ * wordings: new WowDatasetWordings({ fetcher }),
28
+ * });
29
+ * ```
30
+ *
31
+ * Every rejection is a `ViewStoreError`, read as a `WowViewStore`'s are.
32
+ */
33
+ export declare class WowDatasetWordings implements DatasetWordingStore {
34
+ private readonly fetcher;
35
+ constructor(options: WowDatasetWordingsOptions);
36
+ /** Every dataset's wording of the caller's tenant and application, by dataset. */
37
+ list(signal?: AbortSignal): Promise<ReadonlyMap<string, StoredDatasetWording>>;
38
+ /**
39
+ * Writes a dataset's wording at the expected `revision` (`'0'` for one never
40
+ * written), whole: what it leaves out is no longer said. Answers the new
41
+ * revision.
42
+ */
43
+ set(dataset: string, wording: DatasetOverrides, revision: string, context: WriteContext): Promise<string>;
44
+ /** Clears a dataset's wording at the expected `revision`: its derived words stand again. */
45
+ clear(dataset: string, revision: string, context: WriteContext): Promise<void>;
46
+ private send;
47
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export { WowViewStore, type WowViewStoreOptions } from './wowViewStore.js';
2
2
  export { SHARED_OWNER_ID, SYSTEM_OWNER_ID, SYSTEM_TENANT_ID } from './paths.js';
3
3
  export { WowViewStoreErrorCodes } from './errors.js';
4
+ export { WowDatasetWordings, type WowDatasetWordingsOptions, } from './datasetWordings.js';