@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.
- package/README.md +115 -137
- package/README.zh-CN.md +89 -100
- package/dist/datasetWordings.d.ts +47 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.es.js +188 -257
- package/dist/index.es.js.map +1 -1
- package/dist/paths.d.ts +2 -0
- package/dist/remembered.d.ts +9 -0
- package/dist/remembered.es.js +147 -0
- package/dist/remembered.es.js.map +1 -0
- package/dist/v10/datasetWordings.d.ts +46 -0
- package/dist/v10/errors.d.ts +83 -0
- package/dist/v10/generated/index.d.ts +1 -0
- package/dist/v10/generated/view-store/boundedContext.d.ts +36 -0
- package/dist/v10/generated/view-store/dataset_wording/aggregate.d.ts +17 -0
- package/dist/v10/generated/view-store/dataset_wording/commandClient.d.ts +32 -0
- package/dist/v10/generated/view-store/dataset_wording/index.d.ts +3 -0
- package/dist/v10/generated/view-store/dataset_wording/queryClient.d.ts +18 -0
- package/dist/v10/generated/view-store/index.d.ts +5 -0
- package/dist/v10/generated/view-store/types.d.ts +167 -0
- package/dist/v10/generated/view-store/view/aggregate.d.ts +17 -0
- package/dist/v10/generated/view-store/view/commandClient.d.ts +65 -0
- package/dist/v10/generated/view-store/view/index.d.ts +3 -0
- package/dist/v10/generated/view-store/view/queryClient.d.ts +18 -0
- package/dist/v10/generated/view-store/view_preferences/aggregate.d.ts +17 -0
- package/dist/v10/generated/view-store/view_preferences/commandClient.d.ts +22 -0
- package/dist/v10/generated/view-store/view_preferences/index.d.ts +3 -0
- package/dist/v10/generated/view-store/view_preferences/queryClient.d.ts +18 -0
- package/dist/v10/index.d.ts +6 -0
- package/dist/v10/source.d.ts +46 -0
- package/dist/v10/systemViews.d.ts +21 -0
- package/dist/v10/wire.d.ts +25 -0
- package/dist/v10/wowViewStore.d.ts +179 -0
- package/dist/v10.es.js +673 -0
- package/dist/v10.es.js.map +1 -0
- package/dist/wowViewStore.d.ts +13 -0
- 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
|
|
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
|
-
###
|
|
75
|
+
### Dataset wording
|
|
76
76
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
`
|
|
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
|
-
|
|
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
|
|
90
|
-
import {
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
A
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
+
随 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
|
-
|
|
65
|
-
`
|
|
63
|
+
`WowDatasetWordings` 在 `owner/(shared)` 下存租户给数据集写的措辞(视图引擎的数据集覆盖:标题、名词、字段的
|
|
64
|
+
口径、次序与收窄),每个应用、每个数据集一份,按数据集的定义 id 存。把它交给数据集作措辞存储:`DatasetResources`
|
|
65
|
+
每次刷新前读它,按存着的措辞登记每个数据集,并在宿主给了 `editDatasetWording` 时给视图管理器一个「措辞」页签:
|
|
66
66
|
|
|
67
|
-
|
|
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
|
|
74
|
-
import {
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
| `
|
|
103
|
-
|
|
|
104
|
-
|
|
|
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';
|