@jam-overture/loom 0.2.0 → 0.3.0
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/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One pull of a project's live pages, and what it does to the pages a server
|
|
3
|
+
* already holds.
|
|
4
|
+
*
|
|
5
|
+
* The request is deliberately the smallest thing that can be made: a `GET`, the
|
|
6
|
+
* project's key as a bearer, the tag of what is held, and no query at all. A
|
|
7
|
+
* request that could say which reader it was for, or which audience, would put
|
|
8
|
+
* Loom back in the render path (0262) — so the client cannot build one. The
|
|
9
|
+
* door refuses a query as well, and both halves saying so is the point: the
|
|
10
|
+
* property does not rest on either side being well behaved.
|
|
11
|
+
*
|
|
12
|
+
* The work is split in two on purpose. `pullLivePages` makes the request and
|
|
13
|
+
* reads the answer, and is the only part that touches a network. Deciding what
|
|
14
|
+
* the answer means for what is held is `withPullOutcome`, which is a pure
|
|
15
|
+
* function of the two — so every branch a server can take, including the ones
|
|
16
|
+
* that only happen when the door misbehaves, is reachable in a test without a
|
|
17
|
+
* running Loom.
|
|
18
|
+
*/
|
|
19
|
+
import type { AudienceForm } from "../audience/compose.js";
|
|
20
|
+
import { type AudienceRule } from "../audience/rule.js";
|
|
21
|
+
import { type TreeId } from "../ids.js";
|
|
22
|
+
import { type Result } from "../result.js";
|
|
23
|
+
import { type LoomTree } from "../tree/tree.js";
|
|
24
|
+
import { type LivePages } from "./pages.js";
|
|
25
|
+
import { type LiveWindow } from "./window.js";
|
|
26
|
+
/** The one path the client asks for, so no customer's configuration holds it. */
|
|
27
|
+
export declare const LIVE_PAGES_PATH = "/api/pages/live";
|
|
28
|
+
/** `10s`. A pull nobody is waiting for, with a ceiling well inside the interval. */
|
|
29
|
+
export declare const DEFAULT_PULL_CEILING_MS = 10000;
|
|
30
|
+
/**
|
|
31
|
+
* Why a pull did not move what the server holds.
|
|
32
|
+
*
|
|
33
|
+
* The reason is what a log is read for, and the five are the five a deployment
|
|
34
|
+
* acts on differently: its configuration is wrong, Loom is unreachable, Loom is
|
|
35
|
+
* slow, its key is not accepted, or the answer was not one the client can
|
|
36
|
+
* believe. None of them costs the page.
|
|
37
|
+
*/
|
|
38
|
+
export type SitePullFailure = {
|
|
39
|
+
readonly reason: "unconfigured" | "unreachable" | "expired" | "refused" | "unreadable";
|
|
40
|
+
readonly detail: string;
|
|
41
|
+
readonly status?: number;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* One page's segment rules as the door answers them: the page, and its list in
|
|
45
|
+
* the order the portal set (0371).
|
|
46
|
+
*/
|
|
47
|
+
export type LivePageRules = {
|
|
48
|
+
readonly treeId: TreeId;
|
|
49
|
+
readonly rules: readonly AudienceRule[];
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* One page's segment forms as the door answers them: the page, and a delta per
|
|
53
|
+
* segment that has one, each authored against the revision of the page it
|
|
54
|
+
* arrives beside (0371).
|
|
55
|
+
*/
|
|
56
|
+
export type LivePageForms = {
|
|
57
|
+
readonly treeId: TreeId;
|
|
58
|
+
readonly forms: readonly AudienceForm[];
|
|
59
|
+
};
|
|
60
|
+
/** What one pull did: brought pages and their rules, confirmed the ones held, or failed. */
|
|
61
|
+
export type SitePullOutcome = {
|
|
62
|
+
readonly kind: "fresh";
|
|
63
|
+
readonly pages: readonly LoomTree[];
|
|
64
|
+
readonly rules: readonly LivePageRules[];
|
|
65
|
+
readonly forms: readonly LivePageForms[];
|
|
66
|
+
readonly window: LiveWindow;
|
|
67
|
+
readonly tag: string | undefined;
|
|
68
|
+
} | {
|
|
69
|
+
readonly kind: "unchanged";
|
|
70
|
+
} | {
|
|
71
|
+
readonly kind: "failed";
|
|
72
|
+
readonly failure: SitePullFailure;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* The shape of `fetch` a pull needs, which is narrower than the global.
|
|
76
|
+
*
|
|
77
|
+
* Narrower so that a test can be a function rather than a server, and so that a
|
|
78
|
+
* host behind a proxy can hand over its own client without implementing the
|
|
79
|
+
* parts of `fetch` nothing here calls.
|
|
80
|
+
*/
|
|
81
|
+
export type PullFetch = (url: string, init: {
|
|
82
|
+
readonly method: "GET";
|
|
83
|
+
readonly headers: Readonly<Record<string, string>>;
|
|
84
|
+
readonly signal: AbortSignal;
|
|
85
|
+
readonly cache: "no-store";
|
|
86
|
+
}) => Promise<Response>;
|
|
87
|
+
export type PullLivePagesOptions = {
|
|
88
|
+
/**
|
|
89
|
+
* Where this project's Loom deployment is, as an origin — `https://loom.example.com`.
|
|
90
|
+
* The path is this module's, so a project's configuration never carries one.
|
|
91
|
+
*/
|
|
92
|
+
readonly deployment: string;
|
|
93
|
+
/**
|
|
94
|
+
* The project's public key, the one its pages already post signals with
|
|
95
|
+
* (0298). Opaque here: what a key may look like is the door's to say, and a
|
|
96
|
+
* second spelling of the rule in the client would be a second place to be
|
|
97
|
+
* wrong.
|
|
98
|
+
*/
|
|
99
|
+
readonly key: string;
|
|
100
|
+
/** How long to wait for the door. `DEFAULT_PULL_CEILING_MS` when unset. */
|
|
101
|
+
readonly ceilingMs?: number;
|
|
102
|
+
/** `globalThis.fetch` unless a host hands over its own. */
|
|
103
|
+
readonly fetch?: PullFetch;
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* The URL a pull asks for, which by construction carries no query and no
|
|
107
|
+
* fragment.
|
|
108
|
+
*
|
|
109
|
+
* A configured deployment can hold either, by a copied address or a trailing
|
|
110
|
+
* `?`, and a query would be refused by the door with a `400` once a minute for
|
|
111
|
+
* ever. Clearing both here means the one thing the client must not send is not
|
|
112
|
+
* something it can send.
|
|
113
|
+
*
|
|
114
|
+
* The path is appended to whatever path the deployment carries rather than
|
|
115
|
+
* resolved against its origin, so a Loom served under a path keeps it:
|
|
116
|
+
* resolving `/api/pages/live` against `https://example.com/loom` would quietly
|
|
117
|
+
* drop the `/loom`.
|
|
118
|
+
*/
|
|
119
|
+
export declare const livePagesUrlOf: (deployment: string) => Result<URL, SitePullFailure>;
|
|
120
|
+
/**
|
|
121
|
+
* Asks the door once, and says what the answer was.
|
|
122
|
+
*
|
|
123
|
+
* It never throws and never rejects: a network that is down, a Loom that is
|
|
124
|
+
* slow and a door answering something unreadable are all outcomes, because a
|
|
125
|
+
* caller that has to catch has a path on which the page is lost (0358 clause
|
|
126
|
+
* 4).
|
|
127
|
+
*/
|
|
128
|
+
export declare const pullLivePages: (options: PullLivePagesOptions, held: LivePages) => Promise<SitePullOutcome>;
|
|
129
|
+
/**
|
|
130
|
+
* What the server holds after an outcome: the pure half, and the only place the
|
|
131
|
+
* holding changes.
|
|
132
|
+
*
|
|
133
|
+
* A failed pull returns the pages untouched with one more failure against them,
|
|
134
|
+
* which is clause 4 of the decision behind the pull (0358) as a line of code:
|
|
135
|
+
* freshness is what is lost, never the page. A tag moves only with the pages it
|
|
136
|
+
* names, so what is sent back as `If-None-Match` always describes what is held,
|
|
137
|
+
* and the rules move only with the pages they sort readers of (0371 clause 4).
|
|
138
|
+
*
|
|
139
|
+
* The window moves with them for the same reason, and it has to: its `number`
|
|
140
|
+
* is what a reader with no pin is pinned to and its `held` versions are of the
|
|
141
|
+
* pages beside it, so a window from one pull over another pull's pages would
|
|
142
|
+
* pin new readers to a state those pages were never in (0383 clause 5).
|
|
143
|
+
*/
|
|
144
|
+
export declare const withPullOutcome: (held: LivePages, outcome: SitePullOutcome, at: number) => LivePages;
|
|
145
|
+
/** One sentence for a log, naming what failed and what it cost. */
|
|
146
|
+
export declare const describeSitePullFailure: (failure: SitePullFailure) => string;
|
|
147
|
+
//# sourceMappingURL=pull.d.ts.map
|
|
@@ -0,0 +1,398 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One pull of a project's live pages, and what it does to the pages a server
|
|
3
|
+
* already holds.
|
|
4
|
+
*
|
|
5
|
+
* The request is deliberately the smallest thing that can be made: a `GET`, the
|
|
6
|
+
* project's key as a bearer, the tag of what is held, and no query at all. A
|
|
7
|
+
* request that could say which reader it was for, or which audience, would put
|
|
8
|
+
* Loom back in the render path (0262) — so the client cannot build one. The
|
|
9
|
+
* door refuses a query as well, and both halves saying so is the point: the
|
|
10
|
+
* property does not rest on either side being well behaved.
|
|
11
|
+
*
|
|
12
|
+
* The work is split in two on purpose. `pullLivePages` makes the request and
|
|
13
|
+
* reads the answer, and is the only part that touches a network. Deciding what
|
|
14
|
+
* the answer means for what is held is `withPullOutcome`, which is a pure
|
|
15
|
+
* function of the two — so every branch a server can take, including the ones
|
|
16
|
+
* that only happen when the door misbehaves, is reachable in a test without a
|
|
17
|
+
* running Loom.
|
|
18
|
+
*/
|
|
19
|
+
import { z } from "zod";
|
|
20
|
+
import { audienceIdSchema } from "../audience/audience.js";
|
|
21
|
+
import { audienceRuleSchema } from "../audience/rule.js";
|
|
22
|
+
import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
|
|
23
|
+
import { treeIdSchema } from "../ids.js";
|
|
24
|
+
import { err, ok } from "../result.js";
|
|
25
|
+
import { treeDeltaSchema } from "../tree/delta.js";
|
|
26
|
+
import { describeTreeError } from "../tree/errors.js";
|
|
27
|
+
import { parseTree } from "../tree/tree.js";
|
|
28
|
+
import {} from "./pages.js";
|
|
29
|
+
import { WINDOW_OFF } from "./window.js";
|
|
30
|
+
/** The one path the client asks for, so no customer's configuration holds it. */
|
|
31
|
+
export const LIVE_PAGES_PATH = "/api/pages/live";
|
|
32
|
+
/** `10s`. A pull nobody is waiting for, with a ceiling well inside the interval. */
|
|
33
|
+
export const DEFAULT_PULL_CEILING_MS = 10_000;
|
|
34
|
+
/**
|
|
35
|
+
* The URL a pull asks for, which by construction carries no query and no
|
|
36
|
+
* fragment.
|
|
37
|
+
*
|
|
38
|
+
* A configured deployment can hold either, by a copied address or a trailing
|
|
39
|
+
* `?`, and a query would be refused by the door with a `400` once a minute for
|
|
40
|
+
* ever. Clearing both here means the one thing the client must not send is not
|
|
41
|
+
* something it can send.
|
|
42
|
+
*
|
|
43
|
+
* The path is appended to whatever path the deployment carries rather than
|
|
44
|
+
* resolved against its origin, so a Loom served under a path keeps it:
|
|
45
|
+
* resolving `/api/pages/live` against `https://example.com/loom` would quietly
|
|
46
|
+
* drop the `/loom`.
|
|
47
|
+
*/
|
|
48
|
+
export const livePagesUrlOf = (deployment) => {
|
|
49
|
+
const configured = deployment.trim();
|
|
50
|
+
if (configured === "") {
|
|
51
|
+
return err({
|
|
52
|
+
reason: "unconfigured",
|
|
53
|
+
detail: "no Loom deployment was configured to pull live pages from",
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
const url = (() => {
|
|
57
|
+
try {
|
|
58
|
+
return new URL(configured);
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
return undefined;
|
|
62
|
+
}
|
|
63
|
+
})();
|
|
64
|
+
if (url === undefined) {
|
|
65
|
+
return err({ reason: "unconfigured", detail: `not a URL to pull from: ${configured}` });
|
|
66
|
+
}
|
|
67
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
68
|
+
return err({
|
|
69
|
+
reason: "unconfigured",
|
|
70
|
+
detail: `live pages are pulled over http or https, not ${url.protocol}`,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
url.pathname = `${url.pathname.replace(/\/+$/, "")}${LIVE_PAGES_PATH}`;
|
|
74
|
+
url.search = "";
|
|
75
|
+
url.hash = "";
|
|
76
|
+
return ok(url);
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* The envelope the door answers. The trees inside are parsed one at a time, so
|
|
80
|
+
* a refusal can say which page could not be read.
|
|
81
|
+
*
|
|
82
|
+
* `rules` and `forms` are optional because a door from before 0371 answers
|
|
83
|
+
* neither, and a site pulling from one has no segments — which is true of it
|
|
84
|
+
* rather than a guess. They are read separately for the same reason: a door
|
|
85
|
+
* that answers rules and no forms is every deployment whose segments are still
|
|
86
|
+
* only names. `window` is optional for the same reason and reads as *Off*
|
|
87
|
+
* (0383): a door from before it holds nobody.
|
|
88
|
+
*/
|
|
89
|
+
const answerSchema = z.object({
|
|
90
|
+
pages: z.array(z.unknown()),
|
|
91
|
+
rules: z.array(z.unknown()).optional(),
|
|
92
|
+
forms: z.array(z.unknown()).optional(),
|
|
93
|
+
window: z.unknown().optional(),
|
|
94
|
+
});
|
|
95
|
+
const pageRulesSchema = z.object({
|
|
96
|
+
treeId: treeIdSchema,
|
|
97
|
+
rules: z.array(audienceRuleSchema),
|
|
98
|
+
});
|
|
99
|
+
const pageFormsSchema = z.object({
|
|
100
|
+
treeId: treeIdSchema,
|
|
101
|
+
forms: z.array(z.object({ audienceId: audienceIdSchema, delta: treeDeltaSchema })),
|
|
102
|
+
});
|
|
103
|
+
/**
|
|
104
|
+
* The door's `window` (0383): *Off*, or the window's length with what a pin
|
|
105
|
+
* needs to be resolved against.
|
|
106
|
+
*
|
|
107
|
+
* The numbers are milliseconds — when each state of the pages was made — so a
|
|
108
|
+
* whole number is the only shape worth reading; `ms` is a length and the other
|
|
109
|
+
* two are instants, and all three are compared and never counted.
|
|
110
|
+
*
|
|
111
|
+
* `held`'s trees are read one at a time below, so a refusal can say which page
|
|
112
|
+
* could not be read, which is what `pages` already does.
|
|
113
|
+
*/
|
|
114
|
+
const windowSchema = z.union([
|
|
115
|
+
z.object({ ms: z.literal(0) }),
|
|
116
|
+
z.object({
|
|
117
|
+
ms: z.number().int().positive(),
|
|
118
|
+
floor: z.number().int().nonnegative(),
|
|
119
|
+
number: z.number().int().nonnegative(),
|
|
120
|
+
held: z.array(z.unknown()),
|
|
121
|
+
}),
|
|
122
|
+
]);
|
|
123
|
+
const heldPageSchema = z.object({
|
|
124
|
+
treeId: treeIdSchema,
|
|
125
|
+
versions: z.array(z.object({ until: z.number().int().nonnegative(), tree: z.unknown() })),
|
|
126
|
+
});
|
|
127
|
+
const refusals = {
|
|
128
|
+
401: "the project key was not accepted: it is not a key this deployment issued, it has been replaced, or it is a publish key",
|
|
129
|
+
403: "the project is closed, and a closed project serves no live pages",
|
|
130
|
+
};
|
|
131
|
+
const unreadable = (detail) => ({
|
|
132
|
+
kind: "failed",
|
|
133
|
+
failure: { reason: "unreadable", detail, status: 200 },
|
|
134
|
+
});
|
|
135
|
+
/**
|
|
136
|
+
* A list the door answered per page, read against the pages it answered beside
|
|
137
|
+
* them.
|
|
138
|
+
*
|
|
139
|
+
* **Any entry that cannot be read refuses the whole answer**, rather than
|
|
140
|
+
* dropping that page's. A page whose rules were dropped files every reader
|
|
141
|
+
* under `aud_everyone`, which is a segment's page views quietly counted as
|
|
142
|
+
* everybody's — the number that looks right for ever (0284). A page whose
|
|
143
|
+
* forms were dropped serves every reader the base while their signals still
|
|
144
|
+
* say which segment they were in, which is the same fault one dimension
|
|
145
|
+
* across. Keeping the last whole answer instead is what an unreadable page
|
|
146
|
+
* already does.
|
|
147
|
+
*
|
|
148
|
+
* An entry for a page the answer does not hold, and two entries for one page,
|
|
149
|
+
* are refused for the same reason two pages under one id are: the answer has
|
|
150
|
+
* no single reading.
|
|
151
|
+
*/
|
|
152
|
+
const readPerPage = (answered, pages, label, parse) => {
|
|
153
|
+
const read = [];
|
|
154
|
+
const seen = new Set();
|
|
155
|
+
for (const [index, entry] of answered.entries()) {
|
|
156
|
+
const where = `${label} ${index + 1} of ${answered.length}`;
|
|
157
|
+
const parsed = parse(entry);
|
|
158
|
+
if (!parsed.ok)
|
|
159
|
+
return err(`${where} ${parsed.error}`);
|
|
160
|
+
const { treeId } = parsed.value;
|
|
161
|
+
if (!pages.has(treeId))
|
|
162
|
+
return err(`${where} is for a page the answer does not hold: ${treeId}`);
|
|
163
|
+
if (seen.has(treeId))
|
|
164
|
+
return err(`${where} repeats a page already answered: ${treeId}`);
|
|
165
|
+
seen.add(treeId);
|
|
166
|
+
read.push(parsed.value);
|
|
167
|
+
}
|
|
168
|
+
return ok(read);
|
|
169
|
+
};
|
|
170
|
+
/** Why one entry could not be read, as the clause that follows *rule list 2 of 3*. */
|
|
171
|
+
const unreadableEntry = (issues, noun) => {
|
|
172
|
+
const [issue] = issues;
|
|
173
|
+
const at = issue === undefined ? "" : ` (${issue.path.join(".") || "the entry"}: ${issue.message})`;
|
|
174
|
+
return `is not a page's segment ${noun} this version can read${at}`;
|
|
175
|
+
};
|
|
176
|
+
const readRules = (answered, pages) => readPerPage(answered, pages, "rule list", (entry) => {
|
|
177
|
+
const parsed = pageRulesSchema.safeParse(entry);
|
|
178
|
+
return parsed.success ? ok(parsed.data) : err(unreadableEntry(parsed.error.issues, "rules"));
|
|
179
|
+
});
|
|
180
|
+
/**
|
|
181
|
+
* The forms the door answered.
|
|
182
|
+
*
|
|
183
|
+
* A page with an entry and an empty list is read rather than refused: it is
|
|
184
|
+
* what a door answers for a page whose every form was left out, and it means
|
|
185
|
+
* the same thing as no entry at all.
|
|
186
|
+
*/
|
|
187
|
+
const readForms = (answered, pages) => readPerPage(answered, pages, "form list", (entry) => {
|
|
188
|
+
const parsed = pageFormsSchema.safeParse(entry);
|
|
189
|
+
return parsed.success ? ok(parsed.data) : err(unreadableEntry(parsed.error.issues, "forms"));
|
|
190
|
+
});
|
|
191
|
+
/**
|
|
192
|
+
* The window the door answered, read against the pages it answered beside it.
|
|
193
|
+
*
|
|
194
|
+
* **No `window` at all is *Off*.** That is a deployment from before 0383 and a
|
|
195
|
+
* true statement about it: its readers are not held, and the client has nothing
|
|
196
|
+
* to resolve a pin against.
|
|
197
|
+
*
|
|
198
|
+
* **A `window` that cannot be read refuses the whole answer**, as an unreadable
|
|
199
|
+
* rule list does. Reading it as *Off* would be the cheap branch and it is the
|
|
200
|
+
* wrong one: a server that quietly stops holding readers serves a pinned reader
|
|
201
|
+
* a page newer than the one they were pinned to, which is the flip 0383 exists
|
|
202
|
+
* to remove, and it would do it silently. Keeping the last whole answer costs
|
|
203
|
+
* freshness, says why in the log, and holds every reader on what they had.
|
|
204
|
+
*
|
|
205
|
+
* `number` below `floor` is not refused. The door answers one at or above the
|
|
206
|
+
* other, and an answer where it is not makes every pin unresolvable by
|
|
207
|
+
* `heldVersionFor`'s own arithmetic, which is already the safe reading.
|
|
208
|
+
*/
|
|
209
|
+
const readWindow = (answered, pages) => {
|
|
210
|
+
if (answered === undefined)
|
|
211
|
+
return ok(WINDOW_OFF);
|
|
212
|
+
const parsed = windowSchema.safeParse(answered);
|
|
213
|
+
if (!parsed.success) {
|
|
214
|
+
const [issue] = parsed.error.issues;
|
|
215
|
+
const at = issue === undefined ? "" : ` (${issue.path.join(".") || "the window"}: ${issue.message})`;
|
|
216
|
+
return err(`the reader window is not one this version can read${at}`);
|
|
217
|
+
}
|
|
218
|
+
if (!("floor" in parsed.data))
|
|
219
|
+
return ok(WINDOW_OFF);
|
|
220
|
+
const { ms, floor, number } = parsed.data;
|
|
221
|
+
const held = readPerPage(parsed.data.held, pages, "held page", (entry) => {
|
|
222
|
+
const page = heldPageSchema.safeParse(entry);
|
|
223
|
+
return page.success ? ok(page.data) : err(unreadableEntry(page.error.issues, "versions"));
|
|
224
|
+
});
|
|
225
|
+
if (!held.ok)
|
|
226
|
+
return err(held.error);
|
|
227
|
+
const versions = new Map();
|
|
228
|
+
for (const page of held.value) {
|
|
229
|
+
const read = [];
|
|
230
|
+
for (const [index, version] of page.versions.entries()) {
|
|
231
|
+
const where = `version ${index + 1} of ${page.versions.length} held for ${page.treeId}`;
|
|
232
|
+
const tree = parseTree(version.tree);
|
|
233
|
+
if (!tree.ok) {
|
|
234
|
+
return err(`${where} is not a tree this version can read: ${describeTreeError(tree.error)}`);
|
|
235
|
+
}
|
|
236
|
+
if (tree.value.treeId !== page.treeId) {
|
|
237
|
+
return err(`${where} is a version of another page: ${tree.value.treeId}`);
|
|
238
|
+
}
|
|
239
|
+
read.push({ until: version.until, tree: tree.value });
|
|
240
|
+
}
|
|
241
|
+
if (read.length > 0)
|
|
242
|
+
versions.set(page.treeId, read);
|
|
243
|
+
}
|
|
244
|
+
return ok({ ms, floor, number, held: versions });
|
|
245
|
+
};
|
|
246
|
+
const readPages = async (answer) => {
|
|
247
|
+
const body = await answer.json().catch(() => undefined);
|
|
248
|
+
const envelope = answerSchema.safeParse(body);
|
|
249
|
+
if (!envelope.success) {
|
|
250
|
+
return unreadable("the answer was not `{ pages: [...], rules: [...], forms: [...], window: {...} }`");
|
|
251
|
+
}
|
|
252
|
+
const pages = [];
|
|
253
|
+
const seen = new Set();
|
|
254
|
+
for (const [index, page] of envelope.data.pages.entries()) {
|
|
255
|
+
const where = `page ${index + 1} of ${envelope.data.pages.length}`;
|
|
256
|
+
const parsed = parseTree(page);
|
|
257
|
+
if (!parsed.ok) {
|
|
258
|
+
return unreadable(`${where} is not a tree this version can read: ${describeTreeError(parsed.error)}`);
|
|
259
|
+
}
|
|
260
|
+
if (seen.has(parsed.value.treeId)) {
|
|
261
|
+
/*
|
|
262
|
+
* The door answers one page per id, so two under one id is an answer with
|
|
263
|
+
* no single reading: taking the later one would serve a page nobody can
|
|
264
|
+
* see named, and taking the earlier one would hide a change. Keeping the
|
|
265
|
+
* last whole set instead is what every other unreadable answer does.
|
|
266
|
+
*/
|
|
267
|
+
return unreadable(`${where} repeats a page already answered: ${parsed.value.treeId}`);
|
|
268
|
+
}
|
|
269
|
+
seen.add(parsed.value.treeId);
|
|
270
|
+
pages.push(parsed.value);
|
|
271
|
+
}
|
|
272
|
+
const rules = readRules(envelope.data.rules ?? [], seen);
|
|
273
|
+
if (!rules.ok)
|
|
274
|
+
return unreadable(rules.error);
|
|
275
|
+
const forms = readForms(envelope.data.forms ?? [], seen);
|
|
276
|
+
if (!forms.ok)
|
|
277
|
+
return unreadable(forms.error);
|
|
278
|
+
const window = readWindow(envelope.data.window, seen);
|
|
279
|
+
if (!window.ok)
|
|
280
|
+
return unreadable(window.error);
|
|
281
|
+
return {
|
|
282
|
+
kind: "fresh",
|
|
283
|
+
pages,
|
|
284
|
+
rules: rules.value,
|
|
285
|
+
forms: forms.value,
|
|
286
|
+
window: window.value,
|
|
287
|
+
tag: answer.headers.get("etag") ?? undefined,
|
|
288
|
+
};
|
|
289
|
+
};
|
|
290
|
+
/**
|
|
291
|
+
* Asks the door once, and says what the answer was.
|
|
292
|
+
*
|
|
293
|
+
* It never throws and never rejects: a network that is down, a Loom that is
|
|
294
|
+
* slow and a door answering something unreadable are all outcomes, because a
|
|
295
|
+
* caller that has to catch has a path on which the page is lost (0358 clause
|
|
296
|
+
* 4).
|
|
297
|
+
*/
|
|
298
|
+
export const pullLivePages = async (options, held) => {
|
|
299
|
+
const url = livePagesUrlOf(options.deployment);
|
|
300
|
+
if (!url.ok)
|
|
301
|
+
return { kind: "failed", failure: url.error };
|
|
302
|
+
if (options.key.trim() === "") {
|
|
303
|
+
return {
|
|
304
|
+
kind: "failed",
|
|
305
|
+
failure: { reason: "unconfigured", detail: "no project key was configured to pull with" },
|
|
306
|
+
};
|
|
307
|
+
}
|
|
308
|
+
const ask = options.fetch ?? globalThis.fetch;
|
|
309
|
+
if (ask === undefined) {
|
|
310
|
+
return {
|
|
311
|
+
kind: "failed",
|
|
312
|
+
failure: { reason: "unconfigured", detail: "this runtime has no `fetch` to pull with" },
|
|
313
|
+
};
|
|
314
|
+
}
|
|
315
|
+
const ceiling = ceilingOf(options.ceilingMs, DEFAULT_PULL_CEILING_MS);
|
|
316
|
+
return withCeiling(ceiling, () => ({
|
|
317
|
+
kind: "failed",
|
|
318
|
+
failure: { reason: "expired", detail: `no answer in ${describeCeiling(ceiling)}` },
|
|
319
|
+
}), async (signal) => {
|
|
320
|
+
const answer = await ask(url.value.toString(), {
|
|
321
|
+
method: "GET",
|
|
322
|
+
headers: {
|
|
323
|
+
authorization: `Bearer ${options.key.trim()}`,
|
|
324
|
+
accept: "application/json",
|
|
325
|
+
...(held.tag === undefined ? {} : { "if-none-match": held.tag }),
|
|
326
|
+
},
|
|
327
|
+
signal,
|
|
328
|
+
cache: "no-store",
|
|
329
|
+
}).then((response) => ok(response), (thrown) => err(thrown instanceof Error ? thrown.message : "the request failed with no message"));
|
|
330
|
+
if (!answer.ok) {
|
|
331
|
+
return {
|
|
332
|
+
kind: "failed",
|
|
333
|
+
failure: { reason: "unreachable", detail: `could not reach Loom: ${answer.error}` },
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
const { status } = answer.value;
|
|
337
|
+
if (status === 304) {
|
|
338
|
+
/*
|
|
339
|
+
* Only reachable from a door that answers `304` to a request that named
|
|
340
|
+
* no pages, which this client does not send. Recording it as a pull
|
|
341
|
+
* would say the server is current with pages it does not hold.
|
|
342
|
+
*/
|
|
343
|
+
return held.tag === undefined
|
|
344
|
+
? {
|
|
345
|
+
kind: "failed",
|
|
346
|
+
failure: {
|
|
347
|
+
reason: "unreadable",
|
|
348
|
+
detail: "the door said nothing had changed, for a request that named no pages",
|
|
349
|
+
status,
|
|
350
|
+
},
|
|
351
|
+
}
|
|
352
|
+
: { kind: "unchanged" };
|
|
353
|
+
}
|
|
354
|
+
if (status === 200)
|
|
355
|
+
return readPages(answer.value);
|
|
356
|
+
const refused = refusals[status];
|
|
357
|
+
return {
|
|
358
|
+
kind: "failed",
|
|
359
|
+
failure: refused === undefined
|
|
360
|
+
? { reason: "unreachable", detail: `Loom answered ${status}`, status }
|
|
361
|
+
: { reason: "refused", detail: refused, status },
|
|
362
|
+
};
|
|
363
|
+
});
|
|
364
|
+
};
|
|
365
|
+
/**
|
|
366
|
+
* What the server holds after an outcome: the pure half, and the only place the
|
|
367
|
+
* holding changes.
|
|
368
|
+
*
|
|
369
|
+
* A failed pull returns the pages untouched with one more failure against them,
|
|
370
|
+
* which is clause 4 of the decision behind the pull (0358) as a line of code:
|
|
371
|
+
* freshness is what is lost, never the page. A tag moves only with the pages it
|
|
372
|
+
* names, so what is sent back as `If-None-Match` always describes what is held,
|
|
373
|
+
* and the rules move only with the pages they sort readers of (0371 clause 4).
|
|
374
|
+
*
|
|
375
|
+
* The window moves with them for the same reason, and it has to: its `number`
|
|
376
|
+
* is what a reader with no pin is pinned to and its `held` versions are of the
|
|
377
|
+
* pages beside it, so a window from one pull over another pull's pages would
|
|
378
|
+
* pin new readers to a state those pages were never in (0383 clause 5).
|
|
379
|
+
*/
|
|
380
|
+
export const withPullOutcome = (held, outcome, at) => {
|
|
381
|
+
if (outcome.kind === "failed")
|
|
382
|
+
return { ...held, failures: held.failures + 1 };
|
|
383
|
+
if (outcome.kind === "unchanged")
|
|
384
|
+
return { ...held, pulledAt: at, failures: 0 };
|
|
385
|
+
return {
|
|
386
|
+
pages: new Map(outcome.pages.map((page) => [page.treeId, page])),
|
|
387
|
+
rules: new Map(outcome.rules.filter(({ rules }) => rules.length > 0).map(({ treeId, rules }) => [treeId, rules])),
|
|
388
|
+
forms: new Map(outcome.forms.filter(({ forms }) => forms.length > 0).map(({ treeId, forms }) => [treeId, forms])),
|
|
389
|
+
window: outcome.window,
|
|
390
|
+
tag: outcome.tag,
|
|
391
|
+
pulledAt: at,
|
|
392
|
+
freshAt: at,
|
|
393
|
+
failures: 0,
|
|
394
|
+
};
|
|
395
|
+
};
|
|
396
|
+
/** One sentence for a log, naming what failed and what it cost. */
|
|
397
|
+
export const describeSitePullFailure = (failure) => `live pages were not pulled (${failure.reason}): ${failure.detail}`;
|
|
398
|
+
//# sourceMappingURL=pull.js.map
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The loop that keeps a customer's server current: pull, hold, wait, pull
|
|
3
|
+
* again.
|
|
4
|
+
*
|
|
5
|
+
* This is the one stateful thing in the pull — a server holds its live pages
|
|
6
|
+
* and a timer, and both belong to the process rather than to a request. It is a
|
|
7
|
+
* closure and not a class because there is nothing to inherit and nothing to
|
|
8
|
+
* override: the two functions a host calls are reading what is held and
|
|
9
|
+
* stopping.
|
|
10
|
+
*
|
|
11
|
+
* **A reader waits on it once per server, and only for the first answer**
|
|
12
|
+
* ([0364](../../decisions/0364-a-new-server-waits-for-its-first-pull-before-it-serves-and-never-waits-again.md)).
|
|
13
|
+
* The first pull is made at once rather than after an interval, and a render
|
|
14
|
+
* that asks `ready()` before it has settled waits for it — so the first reader
|
|
15
|
+
* on a new server gets the live page rather than the page as built and then a
|
|
16
|
+
* different one on the next request. A pull that fails answers at once, and
|
|
17
|
+
* the wait gives up after `DEFAULT_FIRST_WAIT_MS` only when Loom says nothing
|
|
18
|
+
* at all; either way the page as built is served and the pull carries on.
|
|
19
|
+
*
|
|
20
|
+
* After the first answer nothing waits again: the next pull is scheduled only
|
|
21
|
+
* when the last has settled, so a slow Loom stretches the interval instead of
|
|
22
|
+
* stacking requests behind it, and a render reads whatever is held.
|
|
23
|
+
*/
|
|
24
|
+
import { type LivePages } from "./pages.js";
|
|
25
|
+
import { type PullLivePagesOptions, type SitePullOutcome } from "./pull.js";
|
|
26
|
+
/** A minute, which is a change live within a minute of somebody accepting it. */
|
|
27
|
+
export declare const DEFAULT_PULL_INTERVAL_MS = 60000;
|
|
28
|
+
/**
|
|
29
|
+
* How long a render waits for a new server's first answer, when Loom says
|
|
30
|
+
* nothing at all.
|
|
31
|
+
*
|
|
32
|
+
* It is not a guess at how long Loom takes: a refusal or a failed connection
|
|
33
|
+
* ends the wait at once. It is the bound on a hang, which nothing else can tell
|
|
34
|
+
* apart from slowness, and it is set long enough that only a Loom that is down
|
|
35
|
+
* reaches it. The portal waits as long for its own store.
|
|
36
|
+
*/
|
|
37
|
+
export declare const DEFAULT_FIRST_WAIT_MS = 5000;
|
|
38
|
+
/**
|
|
39
|
+
* How the loop waits, as a function, so a test can drive it without a clock.
|
|
40
|
+
*
|
|
41
|
+
* It answers with its own cancel rather than a handle, which is the only part
|
|
42
|
+
* of a timer this module uses and the part every runtime spells differently.
|
|
43
|
+
*/
|
|
44
|
+
export type PullSchedule = (run: () => void, afterMs: number) => () => void;
|
|
45
|
+
export type StartPullingOptions = PullLivePagesOptions & {
|
|
46
|
+
/** How long between pulls. `DEFAULT_PULL_INTERVAL_MS` when unset. */
|
|
47
|
+
readonly intervalMs?: number;
|
|
48
|
+
/** How long `ready()` waits on a silent Loom. `DEFAULT_FIRST_WAIT_MS` when unset. */
|
|
49
|
+
readonly firstWaitMs?: number;
|
|
50
|
+
/**
|
|
51
|
+
* Told of every outcome, after what is held has moved.
|
|
52
|
+
*
|
|
53
|
+
* This is where a deployment logs a failed pull, and the only way it learns
|
|
54
|
+
* of one: nothing here writes to a console, because a library that logs on
|
|
55
|
+
* its host's behalf logs in the wrong format and at the wrong level.
|
|
56
|
+
*/
|
|
57
|
+
readonly onOutcome?: (outcome: SitePullOutcome, held: LivePages) => void;
|
|
58
|
+
readonly now?: () => number;
|
|
59
|
+
readonly schedule?: PullSchedule;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* A running pull: what it holds, a way to pull out of turn, and a way to stop.
|
|
63
|
+
*
|
|
64
|
+
* `ready` is what a render awaits. It answers what is held once the first
|
|
65
|
+
* pull has settled, or once a silent Loom has had `firstWaitMs`, and at once
|
|
66
|
+
* every time after that. `held` answers without waiting, for a caller that
|
|
67
|
+
* would rather have the page as built than wait at all.
|
|
68
|
+
*
|
|
69
|
+
* `pullNow` answers the pull already in flight rather than starting a second,
|
|
70
|
+
* so a host that pulls on a deploy hook cannot double the load on the door.
|
|
71
|
+
*/
|
|
72
|
+
export type LivePullLoop = {
|
|
73
|
+
readonly ready: () => Promise<LivePages>;
|
|
74
|
+
readonly held: () => LivePages;
|
|
75
|
+
readonly pullNow: () => Promise<SitePullOutcome>;
|
|
76
|
+
readonly stop: () => void;
|
|
77
|
+
};
|
|
78
|
+
export declare const startPullingLivePages: (options: StartPullingOptions) => LivePullLoop;
|
|
79
|
+
//# sourceMappingURL=pulling.d.ts.map
|