@ahoo-wang/wow-view-store 9.2.0-rc.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2024] [ahoo wang <ahoowang@qq.com>]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,227 @@
+# `@ahoo-wang/wow-view-store`
+
+[简体中文](./README.zh-CN.md)
+
+The view engine's `ViewStore` on a Wow server: the saved views and preferences
+of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md), kept by the
+[view store](../../view-store/README.md) — two Wow aggregates, served by the
+standalone `wow-view-store-server` or by any Wow service that embeds
+`wow-view-store-starter`.
+
+Released with Wow 9.2.0, from the same tag and with the same version, together
+with the view engine and the view store's server modules.
+
+> **Compatibility.** From 9.2.0 on, a patch release never breaks the public
+> surface (the exports of the entry and the error codes); a minor release may,
+> and its release notes list every break with the steps to follow. Keep the Wow
+> packages on one minor, as [version ranges](https://wow.ahoo.me/guide/typescript/compatibility#version-ranges)
+> explains.
+
+## Use
+
+Peer dependencies: `@ahoo-wang/fetcher`, `@ahoo-wang/wow-client` and
+`@ahoo-wang/wow-view-engine`, and the peers those declare, which a host installs
+with them: `@ahoo-wang/fetcher-decorator` and `@ahoo-wang/fetcher-eventstream`
+(wow-client's), and the view engine's optional `react`, `react-dom`,
+`react-router` and `mingo` where its own entries need them. Node `>=22.12.0` or
+a current browser; TypeScript 6 or later.
+
+`WowViewStore` takes a fetcher and, optionally, the permissions that drive the
+buttons. It takes no tenant, user or application: the fetcher's interceptors
+carry who is asking, as they do for every other Wow request of the host.
+
+<!-- typecheck-context
+import type { QueryApi } from '@ahoo-wang/wow-client';
+import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
+declare const orders: ViewDefinition;
+declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
+declare const tokenStorage: TokenStorage;
+declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
+-->
+
+```ts
+import { Fetcher } from '@ahoo-wang/fetcher';
+import {
+  ResourceAttributionRequestInterceptor,
+  type TokenStorage,
+} from '@ahoo-wang/fetcher-cosec';
+import { ViewEngine } from '@ahoo-wang/wow-view-engine';
+import { WowViewStore } from '@ahoo-wang/wow-view-store';
+
+// The gateway in front of the view store. In a host, the fetcher already
+// carries CoSec's interceptors: the authorization, `CoSec-App-Id`
+// (CoSecRequestInterceptor) and the path's {tenantId} and {ownerId}
+// (ResourceAttributionRequestInterceptor, from the token).
+const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
+fetcher.interceptors.request.use(
+  new ResourceAttributionRequestInterceptor({ tokenStorage }),
+);
+
+const engine = new ViewEngine({
+  store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
+  resources: [{ definition: orders, source: ordersSource }],
+});
+```
+
+`permissions` decides which buttons are enabled, never what a write may do: the
+server trusts its paths, and the CoSec gateway decides who may use which. Give
+`createShared` and `changeAudience` by the role that may write
+`owner/(shared)` — creating a shared view, claiming one and sharing a personal
+one all need it. Left out, everything is allowed — but the engine's
+`editSystem` (publishing, editing and unpublishing stored system views) is
+off unless the host's answer says `true`: give it by the role the gateway
+admits to `tenant/(platform)/owner/(system)` (`view-store/README.md`, 「System views」).
+
+### A host nobody signs in to
+
+Without a token, nothing fills the path's tenant and owner. Such a host adds an
+interceptor of its own that fills defaults where the request gives none, and
+names its application; with the owner `(shared)` (`SHARED_OWNER_ID`) it has
+shared views and shared preferences only, so its permissions leave
+`createPersonal` off.
+
+<!-- typecheck-context
+import { Fetcher } from '@ahoo-wang/fetcher';
+declare const fetcher: Fetcher;
+-->
+
+```ts
+import type { FetchExchange, RequestInterceptor } from '@ahoo-wang/fetcher';
+import { SHARED_OWNER_ID } from '@ahoo-wang/wow-view-store';
+
+class ConsoleDefaults implements RequestInterceptor {
+  readonly name = 'ConsoleDefaults';
+  readonly order = 0;
+
+  intercept(exchange: FetchExchange): void {
+    const path = exchange.ensureRequestUrlParams().path;
+    path.tenantId ??= '(0)';
+    path.ownerId ??= SHARED_OWNER_ID;
+    exchange.ensureRequestHeaders()['CoSec-App-Id'] = 'console';
+  }
+}
+
+fetcher.interceptors.request.use(new ConsoleDefaults());
+```
+
+## How it maps the port
+
+Every route is under `/view-store/tenant/{tenantId}/owner/{ownerId}`, and **the
+owner segment is the audience**: a personal view lives on the caller's own path,
+a shared one on `owner/(shared)`.
+
+| Port                               | Request                                                                                                                                                                                |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 |
+| `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                                           |
+| `create`                           | `POST …/view` on the path of its `scope` (`system`: `tenant/(platform)/owner/(system)`); the server generates the id                                                                   |
+| `save`, `rename`, `delete`         | `PUT …/view/{id}/save`, `/rename`, `DELETE …/view/{id}` on the view's path                                                                                                             |
+| `changeAudience('shared')`         | `PUT …/view/{id}/share` on the view's path                                                                                                                                             |
+| `changeAudience('personal')`       | `PUT …/view/{id}/claim` on the caller's own path                                                                                                                                       |
+| `getPreferences`, `setPreferences` | `GET`, `PUT …/definitions/{definitionId}/preferences` on the caller's path                                                                                                             |
+
+A list answers in the port's order — the system views, then the shared views,
+then the caller's, each audience oldest first (the server sorts it by
+`firstEventTime`) — and reads at most 1,000 views of each audience, the server's
+query budget: the oldest 1,000. A view past the cut is still read by its id, and
+the workbench asks for one an address names before it sets it aside.
+
+**Writes** send the port's `requestId` as `Command-Request-Id`, the `revision`
+as `Command-Aggregate-Version` (`'0'` for preferences never written), and wait
+for the snapshot. The answer is the view read back at the version the write
+left. `share` and `delete` send `{}`, `claim` no body.
+
+**A retry answers the first outcome.** A write the server refuses as a stale
+version or a repeated request id is looked up by its request id first
+(`GET …/view/requests/{requestId}`, on the path it was sent to and then the
+other one): if the first attempt landed, its outcome is the answer. Only then is
+a stale version `CONFLICT`, carrying the view as it is now — or `NOT_FOUND`,
+when the view is gone. A lookup the server fails is no answer: on the path the
+write went to, the outcome is unknown (`UNAVAILABLE`, and a retry is safe); on the
+other path — `(shared)` refuses a caller without the shared role — the write is
+taken as not replayed, and the refusal stands. A write that landed and was moved
+on by another writer before the read back answers the view as the replay route
+gives it, or, if that route cannot be asked, as it was read. Preferences have no such route: the store answers a retry
+with what its own first attempt answered, and a retry whose first answer was
+lost with what is stored, when that is what it wrote.
+
+**Creating is not idempotent on the server**, which generates the id. The store
+remembers the request ids of its own creates (the last 256), and a retry of one
+first asks the replay route on the path of its `scope`: if the first attempt
+landed, that view is the answer, and nothing is posted again. A retry from
+another store instance — another tab, a reload — makes a second view.
+
+**A view that moved.** When another tab shared a view this store remembers as
+personal (or the other way round), the write is refused on the old path; the
+store looks the view up again and sends the write once more to where it is.
+
+**System views.** The server's system views (`GET (shared)/system-views`) are
+configured ones, read-only, and stored ones (`source: 'stored'`), which
+`WowViewStore` lists and reads with `stored: true` on the summary and the
+instance. A stored one is written on `tenant/(platform)/owner/(system)`
+(`SYSTEM_TENANT_ID`, `SYSTEM_OWNER_ID`) whatever the caller's tenant: they are
+global. `create({ scope: 'system', … })` publishes one (a copy: the source
+view stays), `save`, `rename` and `delete` edit and unpublish it;
+`changeAudience` and any write to a configured or code system view are
+`FORBIDDEN` before anything is sent.
+
+A system view's `revision` is a hash of its content, as the engine needs for
+its dirty baseline, while a write expects the aggregate version: the store
+remembers the `version` each read of a stored view gave beside its revision,
+sends that version, and when the engine holds a revision it has no version
+for, reads the view again first — a revision other than the view's is
+`CONFLICT` with the view as it is, and nothing is sent. The answer of a write
+is read back from the system-views route at the version it left. A retry the
+server refuses as a repeated request is found by the replay route on the
+system path, but that route answers a snapshot, whose content hash only the
+server computes: the store answers it with the system view **as it is now**,
+which is the retried write's outcome unless another admin wrote in between.
+A retry whose first attempt moved the view on (so the revision it holds is no
+longer the view's) asks the replay route before it is refused as `CONFLICT`,
+and a retried create of a system view answers the view from the system
+views, flagged and at its hash.
+
+## Errors
+
+Every rejection is the engine's `ViewStoreError`, read by Wow's error code — the
+HTTP status only when an answer carries no code the store knows:
+
+| Server                                                                                                                                                                                                                                                                     | Port          |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `CommandExpectVersionConflict`, `EventVersionConflict`, `SourcingVersionConflict`; without a known code, 409 and 412                                                                                                                                                       | `CONFLICT`    |
+| `NotFound` (also a view of another application), `IllegalAccessDeletedAggregate`; without a known code, 404 and 410                                                                                                                                                        | `NOT_FOUND`   |
+| `IllegalAccessOwnerAggregate`, `IllegalAccessSpaceAggregate`, `IllegalAccessQueryScope`, `SystemViewReadOnly`, `ViewEventStreamClosed`; without a known code, 401 and 403                                                                                                  | `FORBIDDEN`   |
+| `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`     |
+| `IllegalState`, `RequestTimeout`, `TooManyRequests`, `InternalServerError`, `QuerySchemaUnavailable`, `QuerySchemaConflict`; without a known code, any other status; no answer at all                                                                                      | `UNAVAILABLE` |
+| `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` |
+
+Every `ViewStoreError` keeps what it was read from: the request's failure as
+`cause`, the server's `errorCode` as `detail.code` (so a host tells
+`ViewAppRequired` from `ViewInvalid`, both `INVALID`), and on an `UNAVAILABLE`
+the server answered — a 5xx, a timeout it reported, a page that is not JSON —
+`reachable: true`, which the engine says as 「服务端暂时无法处理」 rather than
+「无法连接服务端」.
+
+A repeated request id (`DuplicateRequestId`) is not an error of its own: the
+store looks the first attempt up (above). A path variable left unfilled is the
+host's set-up — its interceptors do not fill `{tenantId}`, or `{ownerId}` on a
+personal path — so it is `INVALID`, as the server's own `ViewScopeRequired` is:
+the request is wrong as built, and a retry would send it the same.
+
+A claim the server refuses because shared dashboards show the view carries those
+boards' **titles** in the error's `boards`, as stored, and the view engine says
+the refusal in its own words around them: a title written as a key stays a key,
+said where the refusal is shown. The `message` keeps the server's words, for
+logs.
+
+`WowViewStoreErrorCodes` names the view store's own codes.
+
+## Testing
+
+- `pnpm --filter @ahoo-wang/wow-view-store test` — unit tests against a fake
+  server, the public surface and the API report.
+- The port's conformance suite runs over `WowViewStore` against a view store
+  server in `typescript/integration-test` (`test/view-store/`), with the tenant
+  and application isolation.
+
+Licensed under the Apache License, Version 2.0.

package/README.zh-CN.md

@@ -0,0 +1,174 @@
+# `@ahoo-wang/wow-view-store`
+
+[English](./README.md)
+
+视图引擎的 `ViewStore` 落在 Wow 服务端上：[`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.zh-CN.md)
+保存的视图与偏好，由[视图存储](../../view-store/README.md)保管——两个 Wow 聚合，由独立的
+`wow-view-store-server` 提供，或由任何引入了 `wow-view-store-starter` 的 Wow 服务提供。
+
+随 Wow 9.2.0 发布，与 Wow 同一个 tag、同一个版本号，与视图引擎和视图存储的服务端模块一起发布。
+
+> **兼容性。** 从 9.2.0 起，补丁版本不破坏公开面（入口的导出与错误码）；次版本可以破坏，它的发布说明
+> 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上，见[版本范围](https://wow.ahoo.me/zh/guide/typescript/compatibility#版本范围)。
+
+## 使用
+
+对等依赖：`@ahoo-wang/fetcher`、`@ahoo-wang/wow-client` 与 `@ahoo-wang/wow-view-engine`，以及它们自己声明、
+宿主要一并安装的对等依赖：wow-client 的 `@ahoo-wang/fetcher-decorator` 与 `@ahoo-wang/fetcher-eventstream`，
+视图引擎的可选依赖 `react`、`react-dom`、`react-router` 与 `mingo`（用到它对应的入口时）。Node `>=22.12.0`
+或当前的浏览器；TypeScript 6 及以上。
+
+`WowViewStore` 接收一个 fetcher，以及可选的、决定按钮是否可用的权限。它不收租户、用户或应用：
+是谁在请求由 fetcher 的拦截器带上，与宿主的其他 Wow 请求一样。
+
+<!-- typecheck-context
+import type { QueryApi } from '@ahoo-wang/wow-client';
+import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
+declare const orders: ViewDefinition;
+declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
+declare const tokenStorage: TokenStorage;
+declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
+-->
+
+```ts
+import { Fetcher } from '@ahoo-wang/fetcher';
+import {
+  ResourceAttributionRequestInterceptor,
+  type TokenStorage,
+} from '@ahoo-wang/fetcher-cosec';
+import { ViewEngine } from '@ahoo-wang/wow-view-engine';
+import { WowViewStore } from '@ahoo-wang/wow-view-store';
+
+// 视图存储前面的网关。宿主里这个 fetcher 已经带着 CoSec 的拦截器：认证、
+// `CoSec-App-Id`（CoSecRequestInterceptor），以及路径里的 {tenantId} 与 {ownerId}
+// （ResourceAttributionRequestInterceptor，取自令牌）。
+const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
+fetcher.interceptors.request.use(
+  new ResourceAttributionRequestInterceptor({ tokenStorage }),
+);
+
+const engine = new ViewEngine({
+  store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
+  resources: [{ definition: orders, source: ordersSource }],
+});
+```
+
+`permissions` 只决定哪些按钮可用，从不决定一次写入能不能做：服务端信任路径，谁能用哪条路径由 CoSec
+网关决定。`createShared` 与 `changeAudience` 按能写 `owner/(shared)` 的角色给——新建共享视图、收为个人、设为共享都需要它。不给则全部允许——
+但引擎的 `editSystem`（发布、编辑、取消发布存储的系统视图）只在宿主明确答 `true` 时打开：按网关放行
+`tenant/(platform)/owner/(system)` 的角色给（`view-store/README.md`「System views」）。
+
+### 不登录的宿主
+
+没有令牌，就没有谁去填路径里的租户与所有者。这样的宿主加一个自己的拦截器，在请求没给时填上缺省值，并说明自己
+是哪个应用；所有者填 `(shared)`（`SHARED_OWNER_ID`）时，它只有共享视图与共享偏好，所以它的权限把
+`createPersonal` 关掉。
+
+<!-- typecheck-context
+import { Fetcher } from '@ahoo-wang/fetcher';
+declare const fetcher: Fetcher;
+-->
+
+```ts
+import type { FetchExchange, RequestInterceptor } from '@ahoo-wang/fetcher';
+import { SHARED_OWNER_ID } from '@ahoo-wang/wow-view-store';
+
+class ConsoleDefaults implements RequestInterceptor {
+  readonly name = 'ConsoleDefaults';
+  readonly order = 0;
+
+  intercept(exchange: FetchExchange): void {
+    const path = exchange.ensureRequestUrlParams().path;
+    path.tenantId ??= '(0)';
+    path.ownerId ??= SHARED_OWNER_ID;
+    exchange.ensureRequestHeaders()['CoSec-App-Id'] = 'console';
+  }
+}
+
+fetcher.interceptors.request.use(new ConsoleDefaults());
+```
+
+## 端口怎样落到请求上
+
+所有路由都在 `/view-store/tenant/{tenantId}/owner/{ownerId}` 之下，**所有者段就是受众**：个人视图在调用者
+自己的路径上，共享视图在 `owner/(shared)` 上。
+
+| 端口                               | 请求                                                                                                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list`                             | 调用者路径与 `(shared)` 上的快照列表，只投影摘要的字段（`state.config.kind`，不含配置），以及 `GET (shared)/system-views?definitionId=`，三个请求一起发 |
+| `get`                              | 在上次见到这个视图的地方按 id 读快照；没见过的 id 依次在调用者路径、`(shared)`、系统视图上找                                                            |
+| `create`                           | 在其 `scope` 对应的路径上 `POST …/view`（`system`：`tenant/(platform)/owner/(system)`）；id 由服务端生成                                                |
+| `save`、`rename`、`delete`         | 在视图所在路径上 `PUT …/view/{id}/save`、`/rename`，`DELETE …/view/{id}`                                                                                |
+| `changeAudience('shared')`         | 在视图所在路径上 `PUT …/view/{id}/share`                                                                                                                |
+| `changeAudience('personal')`       | 在调用者自己的路径上 `PUT …/view/{id}/claim`                                                                                                            |
+| `getPreferences`、`setPreferences` | 调用者路径上的 `GET`、`PUT …/definitions/{definitionId}/preferences`                                                                                    |
+
+列表按端口规定的顺序作答——系统视图、共享视图、调用者的个人视图，每种受众按创建先后（服务端按 `firstEventTime`
+排序）——每种受众最多读 1000 个，即服务端的查询上限：最早的 1000 个。截断之外的视图仍可按 id 读到，地址里点名的
+视图工作台会先按 id 问一次，再决定是不是别的定义的。
+
+**写入**把端口的 `requestId` 作为 `Command-Request-Id`、`revision` 作为 `Command-Aggregate-Version`
+（从没写过的偏好是 `'0'`）发送，并等到快照落地。作答的是按这次写入留下的版本读回的视图。`share` 与 `delete`
+发送 `{}`，`claim` 不带请求体。
+
+**重试答第一次的结果。** 服务端以过期版本或重复的请求 id 拒绝一次写入时，先按请求 id 查一次
+（`GET …/view/requests/{requestId}`，先在这次发往的路径上，再在另一条上）：第一次已经落地，就以它的结果作答。
+之后过期版本才是 `CONFLICT`，带上视图现在的样子——视图已经不在了则是 `NOT_FOUND`。服务端答不上来的查询不算回答：
+在这次发往的路径上，结局未知（`UNAVAILABLE`，重试安全）；在另一条路径上——没有共享角色的调用者在 `(shared)`
+会被拒——就当没有重放，原来的拒绝照旧。已经落地、读回前又被别人推过的写入，以重放路由给的那一版作答；
+那条路由问不了时，以读回的作答。偏好没有这样的路由：
+store 以自己第一次得到的结果回答重试；第一次的回答丢了的重试，在存着的正是它写的内容时，以存着的作答。
+
+**创建在服务端不是幂等的**，id 由服务端生成。store 记着自己发出的创建的请求 id（最近 256 个），
+重试其中一个时先在其 `scope` 的路径上问重放路由：第一次已经落地，就以那个视图作答，不再发一次。
+从另一个 store 实例发出的重试——另一个标签页、刷新之后——会再建一个视图。
+
+**挪了地方的视图。** 另一个标签页把这个 store 记作个人的视图设为了共享（或反过来），写入在旧路径上被拒；
+store 重新找到视图，把写入再发一次到它现在所在的地方。
+
+**系统视图。** 服务端的系统视图（`GET (shared)/system-views`）有配置的，只读；也有存储的（`source: 'stored'`），
+`WowViewStore` 列出、读取它们时在摘要与实例上带 `stored: true`。存储的系统视图是全局的，不管调用者在哪个租户，
+都写在 `tenant/(platform)/owner/(system)`（`SYSTEM_TENANT_ID`、`SYSTEM_OWNER_ID`）上。`create({ scope: 'system', … })`
+发布一个（是复制，源视图不变），`save`、`rename`、`delete` 编辑与取消发布；`changeAudience`，以及对配置的或
+代码声明的系统视图的任何写入，都在发出请求之前就是 `FORBIDDEN`。
+
+系统视图的 `revision` 是内容的散列，引擎的「已改动」基线靠它；而写入要的是聚合版本：store 记着每次读到的存储视图
+在那个 revision 上的 `version`，写入时发这个版本；引擎拿着一个 store 没有版本的 revision 时，先重读一次——
+与视图当前不符的 revision 是 `CONFLICT`，带上视图现在的样子，什么都不发。写入的答复按它留下的版本从系统视图路由
+读回。服务端以重复请求拒绝的重试，会在系统路径上的重放路由里找到，但那条路由答的是快照，内容散列只有服务端算得出：
+store 以系统视图**现在的样子**作答——除非这期间另一位管理员写过，那就是这次重试的结果。第一次已经把视图推过、手里的 revision 已不是视图当前的那个的重试，
+先问重放路由，再以 `CONFLICT` 拒绝；重试的系统视图创建，从系统视图路由读回作答，带标记、用内容散列。
+
+## 错误
+
+所有拒绝都是引擎的 `ViewStoreError`，按 Wow 的错误码读——只有回答里没有 store 认得的错误码时才看 HTTP 状态：
+
+| 服务端                                                                                                                                                                                                                                  | 端口          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `CommandExpectVersionConflict`、`EventVersionConflict`、`SourcingVersionConflict`；没有认得的错误码时 409、412                                                                                                                          | `CONFLICT`    |
+| `NotFound`（别的应用的视图也是）、`IllegalAccessDeletedAggregate`；没有认得的错误码时 404、410                                                                                                                                          | `NOT_FOUND`   |
+| `IllegalAccessOwnerAggregate`、`IllegalAccessSpaceAggregate`、`IllegalAccessQueryScope`、`SystemViewReadOnly`、`ViewEventStreamClosed`；没有认得的错误码时 401、403                                                                     | `FORBIDDEN`   |
+| `ViewInvalid`、`ViewAppRequired`、`ViewScopeRequired`、`BadRequest`、`CommandValidation`、`IllegalArgument`、`DuplicateAggregateId`、`QuerySchemaValidation`；没有认得的错误码时 400、422；fetcher 的拦截器没填的路径变量（什么都没发） | `INVALID`     |
+| `IllegalState`、`RequestTimeout`、`TooManyRequests`、`InternalServerError`、`QuerySchemaUnavailable`、`QuerySchemaConflict`；没有认得的错误码时其余状态；根本没有回答                                                                   | `UNAVAILABLE` |
+| 没有视图存储的服务端（早于它发布的）答的 `404`：列表，或每处都 `404` 且服务端的系统视图也 `404` 的读写                                                                                                                                  | `UNSUPPORTED` |
+
+每个 `ViewStoreError` 都留着它的来处：请求本身的失败是 `cause`，服务端的 `errorCode` 是 `detail.code`（宿主据此分辨同为
+`INVALID` 的 `ViewAppRequired` 与 `ViewInvalid`）；服务端答了话的 `UNAVAILABLE`——5xx、它报的超时、不是 JSON 的页面——带
+`reachable: true`，引擎据此说「服务端暂时无法处理」，而不是「无法连接服务端」。
+
+重复的请求 id（`DuplicateRequestId`）本身不是错误：store 去查第一次的结果（见上）。没填的路径变量是宿主的配置问题——
+拦截器没填 `{tenantId}`，或个人路径上的 `{ownerId}`——所以与服务端自己的 `ViewScopeRequired` 一样是 `INVALID`：
+请求一构造就是错的，重试发出的还是同一个。
+
+服务端因为有共享仪表盘显示着视图而拒绝收为个人时，错误的 `boards` 原样带上那几块看板的**标题**，由视图引擎用自己的话
+说出这次拒绝：以键写的标题仍是键，在显示拒绝的地方说成话。`message` 保留服务端的原话，供日志。
+
+`WowViewStoreErrorCodes` 列出视图存储自己的错误码。
+
+## 测试
+
+- `pnpm --filter @ahoo-wang/wow-view-store test`——对着假服务端的单元测试、公开面与 API 报告。
+- 端口的一致性测试套件在 `typescript/integration-test`（`test/view-store/`）里对着视图存储服务端跑
+  `WowViewStore`，另有租户与应用的隔离测试。
+
+以 Apache License 2.0 许可。