@ahoo-wang/wow-view-store 9.9.0 → 10.0.0-alpha.4
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 +84 -82
- package/README.zh-CN.md +61 -66
- package/dist/datasetWordings.d.ts +24 -25
- package/dist/errors.d.ts +54 -73
- package/dist/generated/index.d.ts +1 -0
- package/dist/generated/view-store/boundedContext.d.ts +36 -0
- package/dist/generated/view-store/dataset_wording/aggregate.d.ts +17 -0
- package/dist/generated/view-store/dataset_wording/commandClient.d.ts +32 -0
- package/dist/generated/view-store/dataset_wording/index.d.ts +3 -0
- package/dist/generated/view-store/dataset_wording/queryClient.d.ts +18 -0
- package/dist/generated/view-store/index.d.ts +5 -0
- package/dist/generated/view-store/types.d.ts +175 -0
- package/dist/generated/view-store/view/aggregate.d.ts +17 -0
- package/dist/generated/view-store/view/commandClient.d.ts +65 -0
- package/dist/generated/view-store/view/index.d.ts +3 -0
- package/dist/generated/view-store/view/queryClient.d.ts +18 -0
- package/dist/generated/view-store/view_preferences/aggregate.d.ts +17 -0
- package/dist/generated/view-store/view_preferences/commandClient.d.ts +22 -0
- package/dist/generated/view-store/view_preferences/index.d.ts +3 -0
- package/dist/generated/view-store/view_preferences/queryClient.d.ts +18 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.es.js +567 -490
- package/dist/index.es.js.map +1 -1
- package/dist/paths.d.ts +0 -32
- package/dist/remembered.d.ts +9 -0
- package/dist/source.d.ts +47 -0
- package/dist/systemViews.d.ts +21 -0
- package/dist/views.d.ts +49 -0
- package/dist/wire.d.ts +20 -73
- package/dist/wowViewStore.d.ts +111 -159
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -2,127 +2,129 @@
|
|
|
2
2
|
|
|
3
3
|
[简体中文](./README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
The view engine's `ViewStore` on
|
|
6
|
-
of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md),
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
The view engine's `ViewStore` on the Wow view store service: the saved views
|
|
6
|
+
and preferences of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md),
|
|
7
|
+
kept by the view store service (`platform/view-store` in the Wow repository) —
|
|
8
|
+
two Wow aggregates, reached through the clients generated from the service's
|
|
9
|
+
Manifest — and the view engine's sources over a Wow service's query routes.
|
|
10
10
|
|
|
11
11
|
Released with Wow, from the same tag and with the same version, together
|
|
12
|
-
with the view engine
|
|
12
|
+
with the view engine.
|
|
13
13
|
|
|
14
|
-
> **Compatibility.**
|
|
15
|
-
>
|
|
16
|
-
>
|
|
17
|
-
> packages on one minor, as [version ranges](https://wow.ahoo.me/
|
|
14
|
+
> **Compatibility.** A patch release never breaks the public surface (the
|
|
15
|
+
> exports of the entry and the error codes); a minor release may, and its
|
|
16
|
+
> release notes list every break with the steps to follow. Keep the Wow
|
|
17
|
+
> packages on one minor, as [version ranges](https://wow.ahoo.me/typescript/compatibility#version-ranges)
|
|
18
18
|
> explains.
|
|
19
19
|
|
|
20
20
|
## Use
|
|
21
21
|
|
|
22
22
|
Peer dependencies: `@ahoo-wang/fetcher`, `@ahoo-wang/wow-client` and
|
|
23
23
|
`@ahoo-wang/wow-view-engine`, and the peers those declare, which a host installs
|
|
24
|
-
with them: `@ahoo-wang/fetcher-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
with them: `@ahoo-wang/fetcher-eventstream` (wow-client's), and the view
|
|
25
|
+
engine's optional `react`, `react-dom`, `react-router` and `mingo` where its
|
|
26
|
+
own entries need them. Node `>=22.12.0` or a current browser; TypeScript 6 or
|
|
27
|
+
later.
|
|
28
28
|
|
|
29
29
|
`WowViewStore` takes a fetcher and, optionally, the permissions that drive the
|
|
30
|
-
buttons. It takes no tenant, user or application: the
|
|
31
|
-
|
|
30
|
+
buttons. It takes no tenant, user or application: the service takes them from
|
|
31
|
+
the principal, which the fetcher's interceptors carry as they do for every
|
|
32
|
+
other Wow request of the host. `viewSourceOf` puts a definition on a query
|
|
33
|
+
route, `datasetCatalogOf` the service's datasets, and `WowDatasetWordings`
|
|
34
|
+
keeps the tenant's wording over them.
|
|
32
35
|
|
|
33
36
|
<!-- typecheck-context
|
|
34
|
-
import type { QueryApi } from '@ahoo-wang/wow-client';
|
|
35
37
|
import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
|
|
36
38
|
declare const orders: ViewDefinition;
|
|
37
|
-
declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
|
|
38
|
-
declare const tokenStorage: TokenStorage;
|
|
39
39
|
declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
|
|
40
40
|
-->
|
|
41
41
|
|
|
42
42
|
```ts
|
|
43
43
|
import { Fetcher } from '@ahoo-wang/fetcher';
|
|
44
|
+
import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client';
|
|
45
|
+
import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
|
|
44
46
|
import {
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
// The
|
|
52
|
-
//
|
|
53
|
-
// (CoSecRequestInterceptor) and the path's {tenantId} and {ownerId}
|
|
54
|
-
// (ResourceAttributionRequestInterceptor, from the token).
|
|
47
|
+
WowDatasetWordings,
|
|
48
|
+
WowViewStore,
|
|
49
|
+
datasetCatalogOf,
|
|
50
|
+
viewSourceOf,
|
|
51
|
+
} from '@ahoo-wang/wow-view-store';
|
|
52
|
+
|
|
53
|
+
// The fetcher's interceptors send the authorization and `CoSec-App-Id`; no
|
|
54
|
+
// path names the tenant or the owner.
|
|
55
55
|
const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
|
|
56
|
-
fetcher.interceptors.request.use(
|
|
57
|
-
new ResourceAttributionRequestInterceptor({ tokenStorage }),
|
|
58
|
-
);
|
|
59
56
|
|
|
60
57
|
const engine = new ViewEngine({
|
|
61
58
|
store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
|
|
62
|
-
resources: [
|
|
59
|
+
resources: [
|
|
60
|
+
{
|
|
61
|
+
definition: orders,
|
|
62
|
+
// Any query route: a generated `…SnapshotQueryClient` fits too.
|
|
63
|
+
source: viewSourceOf(
|
|
64
|
+
new SnapshotQueryClient(
|
|
65
|
+
{ context: 'sales', name: 'order' },
|
|
66
|
+
{ fetcher },
|
|
67
|
+
),
|
|
68
|
+
),
|
|
69
|
+
},
|
|
70
|
+
],
|
|
63
71
|
});
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
`permissions` decides which buttons are enabled, never what a write may do: the
|
|
67
|
-
server trusts its paths, and the CoSec gateway decides who may use which. Give
|
|
68
|
-
`createShared` and `changeAudience` by the role that may write
|
|
69
|
-
`owner/(shared)` — creating a shared view, claiming one and sharing a personal
|
|
70
|
-
one all need it. Left out, everything is allowed — but the engine's
|
|
71
|
-
`editSystem` (publishing, editing and unpublishing stored system views) is
|
|
72
|
-
off unless the host's answer says `true`: give it by the role the gateway
|
|
73
|
-
admits to `tenant/(platform)/owner/(system)` (`view-store/README.md`, 「System views」).
|
|
74
72
|
|
|
75
|
-
|
|
76
|
-
|
|
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`:
|
|
84
|
-
|
|
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;
|
|
95
|
-
declare const fetcher: Fetcher;
|
|
96
|
-
|
|
97
|
-
const directory = new DatasetDirectoryClient();
|
|
73
|
+
// The service's datasets (`GET /wow/dataset`), worded by the tenant.
|
|
98
74
|
const datasets = new DatasetResources(engine, {
|
|
99
|
-
|
|
100
|
-
source: entry =>
|
|
101
|
-
new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
|
|
75
|
+
...datasetCatalogOf(new DatasetClient({ fetcher })),
|
|
102
76
|
wordings: new WowDatasetWordings({ fetcher }),
|
|
103
77
|
});
|
|
104
78
|
await datasets.refresh();
|
|
105
79
|
```
|
|
106
80
|
|
|
81
|
+
`permissions` decides which buttons are enabled, never what a write may do:
|
|
82
|
+
the service authorizes each write. Give `createShared` and `changeAudience` by
|
|
83
|
+
the role that writes the reserved owner `(shared)` (`view-store.shared-writer`
|
|
84
|
+
as shipped) — creating a shared view, claiming one and sharing a personal one
|
|
85
|
+
all need it. Left out, everything is allowed — but the engine's `editSystem`
|
|
86
|
+
(publishing, editing and unpublishing stored system views) is off unless the
|
|
87
|
+
host's answer says `true`: give it by the role that writes `(system)` of
|
|
88
|
+
`(platform)`.
|
|
89
|
+
|
|
90
|
+
`WowDatasetWordings` keeps a tenant's wording over its datasets (the view
|
|
91
|
+
engine's dataset overrides: title, record noun, field labels, order and
|
|
92
|
+
narrowing), one per dataset and application. `DatasetResources` reads it
|
|
93
|
+
before each refresh, registers each dataset in its stored words, and gives the
|
|
94
|
+
view manager its wording tab where the host grants `editDatasetWording`.
|
|
107
95
|
`set(dataset, wording, revision, { requestId })` writes one whole at the
|
|
108
|
-
expected revision (`'0'` for one never written) and `clear` removes it
|
|
109
|
-
|
|
110
|
-
|
|
96
|
+
expected revision (`'0'` for one never written) and `clear` removes it.
|
|
97
|
+
|
|
98
|
+
### How the store talks to the service
|
|
99
|
+
|
|
100
|
+
- **Who is asking** comes from the principal; a shared view is written as
|
|
101
|
+
the reserved owner `(shared)` and a stored system view as `(system)` of
|
|
102
|
+
`(platform)`, which the store says itself with `Wow-Scope`.
|
|
103
|
+
- **Writes** carry the port's request id as `Wow-Request-Id` and its revision
|
|
104
|
+
as `If-Match`; the service deduplicates every write by its request id,
|
|
105
|
+
creates included, so a retry from any tab is answered with the first
|
|
106
|
+
outcome. Setting a view shared or personal waits for the service's saga
|
|
107
|
+
that moves it to its new owner.
|
|
108
|
+
- **Errors** are read by the problem's `code`: a `ViewStoreError` carries it
|
|
109
|
+
as `detail.code` (`WowViewStoreErrorCodes` lists the view store's own), and
|
|
110
|
+
a route the service does not serve (`404` without a code) is `UNSUPPORTED`.
|
|
111
|
+
- **A page's total** is the service's default `BOUNDED` count: the service
|
|
112
|
+
refuses an exact total over HTTP.
|
|
111
113
|
|
|
112
114
|
## Documentation
|
|
113
115
|
|
|
114
|
-
| To | Read
|
|
115
|
-
| ----------------------------------------------------------------------------------------------- |
|
|
116
|
-
| Choose where views live, wire `WowViewStore`, give permissions, serve a host nobody signs in to | [
|
|
117
|
-
| 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/)
|
|
118
|
-
| Run the view store server, its configuration and the gateway rules | [View store](https://wow.ahoo.me/guide/extensions/view-store) |
|
|
116
|
+
| To | Read |
|
|
117
|
+
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| Choose where views live, wire `WowViewStore`, give permissions, serve a host nobody signs in to | [Saved views](https://wow.ahoo.me/typescript/view-engine/storage#wowviewstore-views-on-a-wow-service) |
|
|
119
|
+
| 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/) |
|
|
119
120
|
|
|
120
121
|
## Testing
|
|
121
122
|
|
|
122
|
-
- `pnpm --filter @ahoo-wang/wow-view-store test` — unit tests against
|
|
123
|
-
|
|
124
|
-
- The port's conformance suite runs over `WowViewStore` against
|
|
125
|
-
|
|
126
|
-
and application
|
|
123
|
+
- `pnpm --filter @ahoo-wang/wow-view-store test` — unit tests against the
|
|
124
|
+
service in memory, the public surface and the API report.
|
|
125
|
+
- The port's conformance suite runs over `WowViewStore` against the view store
|
|
126
|
+
service, which `pnpm --dir typescript/integration-test test` starts on
|
|
127
|
+
ports bound to 0 (`test/view-store/`), with the tenant and application
|
|
128
|
+
isolation.
|
|
127
129
|
|
|
128
130
|
Licensed under the Apache License, Version 2.0.
|
package/README.zh-CN.md
CHANGED
|
@@ -2,105 +2,100 @@
|
|
|
2
2
|
|
|
3
3
|
[English](./README.md)
|
|
4
4
|
|
|
5
|
-
视图引擎的 `ViewStore` 落在 Wow
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
视图引擎的 `ViewStore` 落在 Wow 视图存储服务上:[`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.zh-CN.md)
|
|
6
|
+
保存的视图与偏好,由视图存储服务(Wow 仓库中的 `platform/view-store`)保管——两个 Wow 聚合,经由从服务
|
|
7
|
+
Manifest 生成的客户端访问;另有视图引擎在 Wow 服务查询路由上的数据源。
|
|
8
8
|
|
|
9
|
-
随 Wow 发布,与 Wow 同一个 tag
|
|
9
|
+
随 Wow 发布,与 Wow 同一个 tag、同一个版本号,与视图引擎一起发布。
|
|
10
10
|
|
|
11
|
-
> **兼容性。**
|
|
12
|
-
> 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上,见[版本范围](https://wow.ahoo.me/zh/
|
|
11
|
+
> **兼容性。** 补丁版本不破坏公开面(入口的导出与错误码);次版本可以破坏,它的发布说明
|
|
12
|
+
> 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上,见[版本范围](https://wow.ahoo.me/zh/typescript/compatibility#版本范围)。
|
|
13
13
|
|
|
14
14
|
## 使用
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
或当前的浏览器;TypeScript 6 及以上。
|
|
16
|
+
peer 依赖:`@ahoo-wang/fetcher`、`@ahoo-wang/wow-client` 与 `@ahoo-wang/wow-view-engine`,以及它们声明的
|
|
17
|
+
peer,由宿主一并安装:`@ahoo-wang/fetcher-eventstream`(wow-client 的),以及视图引擎自己的入口需要时的可选
|
|
18
|
+
`react`、`react-dom`、`react-router` 与 `mingo`。Node `>=22.12.0` 或当前的浏览器;TypeScript 6 或更高。
|
|
20
19
|
|
|
21
|
-
`WowViewStore` 接收一个 fetcher
|
|
22
|
-
|
|
20
|
+
`WowViewStore` 接收一个 fetcher,以及可选的、决定按钮的权限。它不接收租户、用户或应用:服务从主体
|
|
21
|
+
(principal)取得它们,fetcher 的拦截器像宿主的其他 Wow 请求一样带上它们。`viewSourceOf` 把一个定义放到
|
|
22
|
+
查询路由上,`datasetCatalogOf` 放上服务的数据集,`WowDatasetWordings` 保存租户对它们的措辞。
|
|
23
23
|
|
|
24
24
|
<!-- typecheck-context
|
|
25
|
-
import type { QueryApi } from '@ahoo-wang/wow-client';
|
|
26
25
|
import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
|
|
27
26
|
declare const orders: ViewDefinition;
|
|
28
|
-
declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
|
|
29
|
-
declare const tokenStorage: TokenStorage;
|
|
30
27
|
declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
|
|
31
28
|
-->
|
|
32
29
|
|
|
33
30
|
```ts
|
|
34
31
|
import { Fetcher } from '@ahoo-wang/fetcher';
|
|
32
|
+
import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client';
|
|
33
|
+
import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
|
|
35
34
|
import {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
//
|
|
43
|
-
// `CoSec-App-Id`(CoSecRequestInterceptor),以及路径里的 {tenantId} 与 {ownerId}
|
|
44
|
-
// (ResourceAttributionRequestInterceptor,取自令牌)。
|
|
35
|
+
WowDatasetWordings,
|
|
36
|
+
WowViewStore,
|
|
37
|
+
datasetCatalogOf,
|
|
38
|
+
viewSourceOf,
|
|
39
|
+
} from '@ahoo-wang/wow-view-store';
|
|
40
|
+
|
|
41
|
+
// fetcher 的拦截器带上授权与 `CoSec-App-Id`;路径里不出现租户与 owner。
|
|
45
42
|
const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
|
|
46
|
-
fetcher.interceptors.request.use(
|
|
47
|
-
new ResourceAttributionRequestInterceptor({ tokenStorage }),
|
|
48
|
-
);
|
|
49
43
|
|
|
50
44
|
const engine = new ViewEngine({
|
|
51
45
|
store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
|
|
52
|
-
resources: [
|
|
46
|
+
resources: [
|
|
47
|
+
{
|
|
48
|
+
definition: orders,
|
|
49
|
+
// 任何查询路由都可以:生成的 `…SnapshotQueryClient` 同样适用。
|
|
50
|
+
source: viewSourceOf(
|
|
51
|
+
new SnapshotQueryClient(
|
|
52
|
+
{ context: 'sales', name: 'order' },
|
|
53
|
+
{ fetcher },
|
|
54
|
+
),
|
|
55
|
+
),
|
|
56
|
+
},
|
|
57
|
+
],
|
|
53
58
|
});
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
`permissions` 只决定哪些按钮可用,从不决定一次写入能不能做:服务端信任路径,谁能用哪条路径由 CoSec
|
|
57
|
-
网关决定。`createShared` 与 `changeAudience` 按能写 `owner/(shared)` 的角色给——新建共享视图、收为个人、设为共享都需要它。不给则全部允许——
|
|
58
|
-
但引擎的 `editSystem`(发布、编辑、取消发布存储的系统视图)只在宿主明确答 `true` 时打开:按网关放行
|
|
59
|
-
`tenant/(platform)/owner/(system)` 的角色给(`view-store/README.md`「System views」)。
|
|
60
|
-
|
|
61
|
-
### 数据集措辞
|
|
62
|
-
|
|
63
|
-
`WowDatasetWordings` 在 `owner/(shared)` 下存租户给数据集写的措辞(视图引擎的数据集覆盖:标题、名词、字段的
|
|
64
|
-
口径、次序与收窄),每个应用、每个数据集一份,按数据集的定义 id 存。把它交给数据集作措辞存储:`DatasetResources`
|
|
65
|
-
每次刷新前读它,按存着的措辞登记每个数据集,并在宿主给了 `editDatasetWording` 时给视图管理器一个「措辞」页签:
|
|
66
|
-
|
|
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;
|
|
77
|
-
declare const fetcher: Fetcher;
|
|
78
59
|
|
|
79
|
-
|
|
60
|
+
// 服务的数据集(`GET /wow/dataset`),按租户的措辞注册。
|
|
80
61
|
const datasets = new DatasetResources(engine, {
|
|
81
|
-
|
|
82
|
-
source: entry =>
|
|
83
|
-
new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
|
|
62
|
+
...datasetCatalogOf(new DatasetClient({ fetcher })),
|
|
84
63
|
wordings: new WowDatasetWordings({ fetcher }),
|
|
85
64
|
});
|
|
86
65
|
await datasets.refresh();
|
|
87
66
|
```
|
|
88
67
|
|
|
89
|
-
`
|
|
90
|
-
|
|
68
|
+
`permissions` 只决定按钮是否可用,从不决定写入能做什么:每次写入由服务授权。`createShared` 与
|
|
69
|
+
`changeAudience` 按能写保留 owner `(shared)` 的角色给出(出厂为 `view-store.shared-writer`)——新建共享视图、
|
|
70
|
+
认领共享视图和共享个人视图都需要它。不给时一切都允许——但引擎的 `editSystem`(发布、编辑与撤下存储的系统视图)
|
|
71
|
+
除非宿主明确答 `true`,否则关闭:按能写 `(platform)` 下 `(system)` 的角色给出。
|
|
72
|
+
|
|
73
|
+
`WowDatasetWordings` 保存租户对数据集的措辞(视图引擎的数据集覆盖:标题、记录名词、字段标签、顺序与收窄),
|
|
74
|
+
每个数据集、每个应用一份。`DatasetResources` 每次刷新前读取它,按存储的措辞注册每个数据集,并在宿主授予
|
|
75
|
+
`editDatasetWording` 时给视图管理器加上措辞页。`set(dataset, wording, revision, { requestId })` 在期望的
|
|
76
|
+
修订号上整体写入一份(从未写过的为 `'0'`),`clear` 删除它。
|
|
77
|
+
|
|
78
|
+
### 存储怎样与服务交互
|
|
79
|
+
|
|
80
|
+
- **谁在请求**来自主体;共享视图以保留 owner `(shared)` 写入,存储的系统视图以 `(platform)` 下的 `(system)`
|
|
81
|
+
写入,由存储自己用 `Wow-Scope` 说明。
|
|
82
|
+
- **写入**以 `Wow-Request-Id` 带上端口的请求 id,以 `If-Match` 带上修订号;服务按请求 id 对每次写入去重,
|
|
83
|
+
创建也一样,所以任何标签页的重试都得到第一次的结果。把视图设为共享或个人时,会等服务把它移到新 owner 的 saga。
|
|
84
|
+
- **错误**按 problem 的 `code` 读取:`ViewStoreError` 以 `detail.code` 带着它(`WowViewStoreErrorCodes`
|
|
85
|
+
列出视图存储自己的码),服务不提供的路由(没有码的 `404`)是 `UNSUPPORTED`。
|
|
86
|
+
- **一页的总数**是服务默认的 `BOUNDED` 计数:服务经 HTTP 拒绝精确总数。
|
|
91
87
|
|
|
92
88
|
## 文档
|
|
93
89
|
|
|
94
|
-
| 想做的事 | 读
|
|
95
|
-
| ----------------------------------------------------------------- |
|
|
96
|
-
| 选择视图放在哪里、接入 `WowViewStore`、给出权限、服务不登录的宿主 | [
|
|
97
|
-
| 导出、合同、端口发出的每个请求,以及服务端错误怎样映射到端口 | [wow-view-store 参考](https://wow.ahoo.me/zh/reference/typescript/wow-view-store/)
|
|
98
|
-
| 运行视图存储服务端、它的配置与网关规则 | [视图存储](https://wow.ahoo.me/zh/guide/extensions/view-store) |
|
|
90
|
+
| 想做的事 | 读 |
|
|
91
|
+
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
92
|
+
| 选择视图放在哪里、接入 `WowViewStore`、给出权限、服务不登录的宿主 | [视图存在哪里](https://wow.ahoo.me/zh/typescript/view-engine/storage#wowviewstore-views-on-a-wow-service) |
|
|
93
|
+
| 导出、合同、端口发出的每个请求,以及服务端错误怎样映射到端口 | [wow-view-store 参考](https://wow.ahoo.me/zh/reference/typescript/wow-view-store/) |
|
|
99
94
|
|
|
100
95
|
## 测试
|
|
101
96
|
|
|
102
|
-
- `pnpm --filter @ahoo-wang/wow-view-store test
|
|
103
|
-
-
|
|
104
|
-
`
|
|
97
|
+
- `pnpm --filter @ahoo-wang/wow-view-store test`——对着内存中的服务的单元测试、公开面与 API 报告。
|
|
98
|
+
- 端口的一致性测试套件对着视图存储服务跑 `WowViewStore`,另有租户与应用的隔离测试;
|
|
99
|
+
`pnpm --dir typescript/integration-test test` 把服务起在绑定 0 的端口上(`test/view-store/`)。
|
|
105
100
|
|
|
106
101
|
以 Apache License 2.0 许可。
|
|
@@ -1,39 +1,36 @@
|
|
|
1
1
|
import { Fetcher } from '@ahoo-wang/fetcher';
|
|
2
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. */
|
|
3
|
+
/** How a V10 {@link WowDatasetWordings} reaches the view store service: as a V10 `WowViewStore` does. */
|
|
4
4
|
export interface WowDatasetWordingsOptions {
|
|
5
5
|
/**
|
|
6
|
-
* The fetcher every request goes through, as
|
|
7
|
-
* its interceptors
|
|
8
|
-
* wording is the tenant's
|
|
6
|
+
* The fetcher every request goes through, as the V10
|
|
7
|
+
* `WowViewStoreOptions.fetcher`: its interceptors carry the caller and
|
|
8
|
+
* `CoSec-App-Id`. The wording is the tenant's (an aggregate of the tenant,
|
|
9
|
+
* not of an owner), so no request names a scope.
|
|
9
10
|
*/
|
|
10
11
|
fetcher: Fetcher;
|
|
11
12
|
}
|
|
12
13
|
/**
|
|
13
|
-
* The wording a tenant's administrators keep over its datasets in the
|
|
14
|
+
* The wording a tenant's administrators keep over its datasets in the V10
|
|
14
15
|
* view store (view engine D86): one per dataset of the caller's tenant and
|
|
15
|
-
* application,
|
|
16
|
+
* application, the id derived by the service from the two. Every reader of
|
|
17
|
+
* the tenant reads it; the service decides who writes it (the role that
|
|
18
|
+
* writes the owner `(shared)`, `view-store.shared-writer` as shipped).
|
|
16
19
|
*
|
|
17
20
|
* A host hands it to the datasets it registers as their store of wording
|
|
18
|
-
* (`DatasetCatalog.wordings`, D91)
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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.
|
|
21
|
+
* (`DatasetCatalog.wordings`, D91). The key is the dataset's definition id,
|
|
22
|
+
* `{context}.{dataset}`. Every rejection is a `ViewStoreError`, read as a
|
|
23
|
+
* V10 `WowViewStore`'s are.
|
|
32
24
|
*/
|
|
33
25
|
export declare class WowDatasetWordings implements DatasetWordingStore {
|
|
34
|
-
private readonly
|
|
26
|
+
private readonly commands;
|
|
27
|
+
private readonly snapshots;
|
|
35
28
|
constructor(options: WowDatasetWordingsOptions);
|
|
36
|
-
/**
|
|
29
|
+
/**
|
|
30
|
+
* Every dataset's wording of the caller's tenant and application, by
|
|
31
|
+
* dataset. A cleared one is listed too, saying nothing: its revision is
|
|
32
|
+
* what the next write expects.
|
|
33
|
+
*/
|
|
37
34
|
list(signal?: AbortSignal): Promise<ReadonlyMap<string, StoredDatasetWording>>;
|
|
38
35
|
/**
|
|
39
36
|
* Writes a dataset's wording at the expected `revision` (`'0'` for one never
|
|
@@ -41,7 +38,9 @@ export declare class WowDatasetWordings implements DatasetWordingStore {
|
|
|
41
38
|
* revision.
|
|
42
39
|
*/
|
|
43
40
|
set(dataset: string, wording: DatasetOverrides, revision: string, context: WriteContext): Promise<string>;
|
|
44
|
-
/**
|
|
45
|
-
|
|
46
|
-
|
|
41
|
+
/**
|
|
42
|
+
* Clears a dataset's wording at the expected `revision`: its derived words
|
|
43
|
+
* stand again. Answers the new revision.
|
|
44
|
+
*/
|
|
45
|
+
clear(dataset: string, revision: string, context: WriteContext): Promise<string>;
|
|
47
46
|
}
|
package/dist/errors.d.ts
CHANGED
|
@@ -1,82 +1,62 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { WowProblemError } from '@ahoo-wang/wow-client';
|
|
2
2
|
import { ViewStoreError, ViewStoreErrorCode } from '@ahoo-wang/wow-view-engine';
|
|
3
3
|
/**
|
|
4
|
-
* The view store's own
|
|
5
|
-
*
|
|
4
|
+
* The V10 view store's own problem codes (`ViewStoreRejections` of
|
|
5
|
+
* `platform/view-store`), beside the framework's (`FrameworkErrorCodes` of
|
|
6
|
+
* `@ahoo-wang/wow-client`): generated from the service's Manifest.
|
|
6
7
|
*
|
|
7
|
-
* Named apart from the engine's `ViewStoreErrorCode` (the port's
|
|
8
|
-
* are the server's
|
|
9
|
-
* `detail.code`.
|
|
10
|
-
* `view-store/wow-view-store-api/src/main/kotlin/me/ahoo/wow/viewstore/api/ViewStoreErrorCodes.kt`.
|
|
8
|
+
* Named apart from the engine's `ViewStoreErrorCode` (the port's codes):
|
|
9
|
+
* these are the `code` of the server's problems, which a `ViewStoreError`
|
|
10
|
+
* carries as `detail.code`.
|
|
11
11
|
*/
|
|
12
|
-
export declare const WowViewStoreErrorCodes:
|
|
13
|
-
|
|
14
|
-
readonly
|
|
15
|
-
|
|
16
|
-
readonly
|
|
17
|
-
|
|
18
|
-
readonly SYSTEM_VIEW_READ_ONLY: "
|
|
19
|
-
|
|
20
|
-
readonly VIEW_SCOPE_REQUIRED: "ViewScopeRequired";
|
|
21
|
-
/** The view store's event streams are closed to HTTP queries (HTTP 403). */
|
|
22
|
-
readonly VIEW_EVENT_STREAM_CLOSED: "ViewEventStreamClosed";
|
|
23
|
-
}>;
|
|
12
|
+
export declare const WowViewStoreErrorCodes: {
|
|
13
|
+
readonly APP_REQUIRED: "view-store.app-required";
|
|
14
|
+
readonly INVALID: "view-store.invalid";
|
|
15
|
+
readonly NOT_FOUND: "view-store.not-found";
|
|
16
|
+
readonly OWNER_REQUIRED: "view-store.owner-required";
|
|
17
|
+
readonly REFERENCED_BY_SHARED_DASHBOARD: "view-store.referenced-by-shared-dashboard";
|
|
18
|
+
readonly SYSTEM_VIEW_READ_ONLY: "view-store.system-view-read-only";
|
|
19
|
+
};
|
|
24
20
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
* title as `msg`.
|
|
28
|
-
*/
|
|
29
|
-
export declare const REFERENCED_BY_SHARED_DASHBOARD = "referenced-by-shared-dashboard";
|
|
30
|
-
/**
|
|
31
|
-
* A request that did not succeed, as the store reads it: the server's error,
|
|
32
|
-
* when the server answered with one, and the HTTP status, when a response
|
|
33
|
-
* came back at all.
|
|
21
|
+
* A request that did not succeed, as the store reads it: the server's
|
|
22
|
+
* problem when it answered with one, else what the request threw.
|
|
34
23
|
*/
|
|
35
24
|
export declare class Failure {
|
|
36
25
|
/** What the request threw. */
|
|
37
26
|
readonly cause: unknown;
|
|
38
|
-
/** The server's
|
|
39
|
-
readonly
|
|
40
|
-
/** The status of the failed response; absent when none came back. */
|
|
41
|
-
readonly status?: number | undefined;
|
|
27
|
+
/** The server's problem, when a response came back. */
|
|
28
|
+
readonly problem?: WowProblemError | undefined;
|
|
42
29
|
constructor(
|
|
43
30
|
/** What the request threw. */
|
|
44
31
|
cause: unknown,
|
|
45
|
-
/** The server's
|
|
46
|
-
|
|
47
|
-
/** The
|
|
48
|
-
|
|
49
|
-
/** The server's error code, if it answered with one. */
|
|
50
|
-
get errorCode(): string | undefined;
|
|
51
|
-
get bindingErrors(): readonly BindingError[];
|
|
52
|
-
/**
|
|
53
|
-
* The path variable the fetcher's interceptors never filled, when that is
|
|
54
|
-
* why the request was never sent: the host's set-up is wrong, not the
|
|
55
|
-
* network.
|
|
56
|
-
*/
|
|
57
|
-
get unfilled(): string | undefined;
|
|
32
|
+
/** The server's problem, when a response came back. */
|
|
33
|
+
problem?: WowProblemError | undefined);
|
|
34
|
+
/** The problem's code: a framework code (`wow.*`) or the view store's. */
|
|
35
|
+
get problemCode(): string | undefined;
|
|
58
36
|
/**
|
|
59
|
-
* The port's code
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
37
|
+
* The port's code, **by the problem's code first**: one HTTP status
|
|
38
|
+
* carries several decisions (a `400` is a bad title and a missing
|
|
39
|
+
* application alike). Only an answer without a code the store knows — a
|
|
40
|
+
* gateway's own page, a proxy, a code a later server adds — falls back to
|
|
41
|
+
* the status; a problem the service says a retry may get past is
|
|
42
|
+
* `UNAVAILABLE` whatever its status. A `404` without a code is a route the server does not serve:
|
|
43
|
+
* no view store there (or, on the memory backend, no snapshot query), so
|
|
44
|
+
* `UNSUPPORTED`. No answer at all is `UNAVAILABLE`: the outcome is
|
|
45
|
+
* unknown, and a retry under the same request id is safe, since the
|
|
46
|
+
* server deduplicates it.
|
|
63
47
|
*/
|
|
64
48
|
get code(): ViewStoreErrorCode;
|
|
65
|
-
/**
|
|
66
|
-
* Whether the server (or something in front of it) answered at all: a
|
|
67
|
-
* response came back. An `UNAVAILABLE` that was answered is the server's
|
|
68
|
-
* own error — a 5xx, a timeout it reported — and not the network.
|
|
69
|
-
*/
|
|
49
|
+
/** Whether the server (or something in front of it) answered at all. */
|
|
70
50
|
get reached(): boolean;
|
|
71
51
|
get message(): string;
|
|
52
|
+
/** The port's error, holding what it was read from. */
|
|
53
|
+
toStoreError(): ViewStoreError;
|
|
72
54
|
/**
|
|
73
|
-
*
|
|
74
|
-
* failure as `cause`, the
|
|
75
|
-
* `
|
|
76
|
-
* whether the server answered (`reachable`).
|
|
55
|
+
* What {@link toStoreError} holds, for an error of another code: the
|
|
56
|
+
* request's own failure as `cause`, the problem's code as `detail` (a
|
|
57
|
+
* host tells `view-store.app-required` from `view-store.invalid` by it),
|
|
58
|
+
* and for `UNAVAILABLE` whether the server answered (`reachable`).
|
|
77
59
|
*/
|
|
78
|
-
toStoreError(): ViewStoreError;
|
|
79
|
-
/** {@link toStoreError} with another code: the same failure, read further. */
|
|
80
60
|
held(): {
|
|
81
61
|
cause: unknown;
|
|
82
62
|
detail?: {
|
|
@@ -85,18 +65,19 @@ export declare class Failure {
|
|
|
85
65
|
reachable?: true;
|
|
86
66
|
};
|
|
87
67
|
}
|
|
88
|
-
/** Whether the request id of a write was used before. */
|
|
89
|
-
export declare function isDuplicateRequest(failure: Failure): boolean;
|
|
90
|
-
/**
|
|
91
|
-
* The port's code for a server's answer, **by Wow's error code first**: the
|
|
92
|
-
* code says what the server decided, where one HTTP status carries several
|
|
93
|
-
* decisions (a `400` is a stale version on no server, but a bad title and a
|
|
94
|
-
* missing application alike). Only an answer without a code the store knows
|
|
95
|
-
* — a gateway's own page, a proxy, a code a later server adds — falls back to
|
|
96
|
-
* the status, and no answer at all (a network failure, a timeout, an abort)
|
|
97
|
-
* is `UNAVAILABLE`: the outcome is unknown, and a retry under the same
|
|
98
|
-
* `requestId` is what the port expects.
|
|
99
|
-
*/
|
|
100
|
-
export declare function portCodeOf(errorCode: string | undefined, status: number | undefined): ViewStoreErrorCode;
|
|
101
68
|
/** What a failed request threw, read as a {@link Failure}. */
|
|
102
69
|
export declare function failureOf(error: unknown): Promise<Failure>;
|
|
70
|
+
/**
|
|
71
|
+
* The titles of the shared dashboards a claim refusal names: the problem's
|
|
72
|
+
* `boards` extension member, a list of `{ id, title }` (decision D211). A
|
|
73
|
+
* board without a title is named by its id; anything else is skipped.
|
|
74
|
+
*/
|
|
75
|
+
export declare function boardTitles(extensions: Readonly<Record<string, unknown>> | undefined): string[];
|
|
76
|
+
/**
|
|
77
|
+
* Runs one of the port's methods, so that everything it rejects with is a
|
|
78
|
+
* `ViewStoreError`: a failed request as its code says, anything else — a
|
|
79
|
+
* body that did not parse — as `UNAVAILABLE`, the outcome unknown.
|
|
80
|
+
*/
|
|
81
|
+
export declare function guard<T>(run: () => Promise<T>): Promise<T>;
|
|
82
|
+
/** Runs one request, so that what it throws is a {@link Failure}. */
|
|
83
|
+
export declare function request<T>(run: () => Promise<T>): Promise<T>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './view-store/index.js';
|