@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.
Files changed (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. 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