@jam-overture/loom 0.1.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/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { err, ok } from "../result.js";
|
|
2
|
+
import { parseReaderSignalBatch } from "./signal.js";
|
|
3
|
+
/**
|
|
4
|
+
* The doorway a browser's batches come through.
|
|
5
|
+
*
|
|
6
|
+
* A page is not a trusted author. Everything that arrives here is parsed before
|
|
7
|
+
* it is kept — the shape, the kinds, the tree id's grammar, and the view key's
|
|
8
|
+
* thirty-two characters of nothing — because the alternative is a database
|
|
9
|
+
* column a visitor can write anything into, including the visitor id that 0146
|
|
10
|
+
* exists to refuse.
|
|
11
|
+
*
|
|
12
|
+
* The route handler that serves this is a surface's, not the framework's. What
|
|
13
|
+
* the framework owns is this function: unknown in, a counted outcome or a
|
|
14
|
+
* typed refusal out, no throw either way.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* How many batches one delivery may carry.
|
|
18
|
+
*
|
|
19
|
+
* A broadcaster sends one at a time, so anything above a handful is a retry
|
|
20
|
+
* queue draining after an outage, and that is worth allowing. What it is not
|
|
21
|
+
* worth is unbounded: the parse is the expensive part and an endpoint that will
|
|
22
|
+
* parse as many batches as a body can hold is an endpoint that can be made to
|
|
23
|
+
* spend a minute on one request.
|
|
24
|
+
*/
|
|
25
|
+
export const MAX_BATCHES_PER_DELIVERY = 50;
|
|
26
|
+
export const describeIngestError = (error) => {
|
|
27
|
+
if (error.code === "too-many") {
|
|
28
|
+
return `a delivery may carry ${error.limit} batches and this one carried ${error.given}`;
|
|
29
|
+
}
|
|
30
|
+
if (error.code === "unavailable")
|
|
31
|
+
return `reader signals are unavailable: ${error.detail}`;
|
|
32
|
+
const first = error.issues.at(0);
|
|
33
|
+
return `batch ${error.index} is not a reader signal batch${first === undefined ? "" : `: ${first.path} ${first.message}`}`;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* One batch or a list of them, because both are what senders send:
|
|
37
|
+
* `navigator.sendBeacon` posts a single batch and a queue draining after an
|
|
38
|
+
* outage posts what it has. Distinguishing them at the door costs one check and
|
|
39
|
+
* saves every caller an envelope.
|
|
40
|
+
*/
|
|
41
|
+
const deliveryOf = (input) => (Array.isArray(input) ? input : [input]);
|
|
42
|
+
/**
|
|
43
|
+
* Parse a delivery and keep it.
|
|
44
|
+
*
|
|
45
|
+
* **Nothing is kept unless all of it parses.** A partial accept would mean a
|
|
46
|
+
* sender's retry either duplicates what was taken or drops what was not, and
|
|
47
|
+
* neither is something a browser can be asked to work out. It also means the
|
|
48
|
+
* refusal is actionable: one index, one reason.
|
|
49
|
+
*/
|
|
50
|
+
export const ingestReaderSignals = async (journal, input) => {
|
|
51
|
+
const delivery = deliveryOf(input);
|
|
52
|
+
if (delivery.length > MAX_BATCHES_PER_DELIVERY) {
|
|
53
|
+
return err({ code: "too-many", limit: MAX_BATCHES_PER_DELIVERY, given: delivery.length });
|
|
54
|
+
}
|
|
55
|
+
const batches = [];
|
|
56
|
+
for (const [index, raw] of delivery.entries()) {
|
|
57
|
+
const parsed = parseReaderSignalBatch(raw);
|
|
58
|
+
if (!parsed.ok)
|
|
59
|
+
return err({ code: "invalid-delivery", index, issues: parsed.error.issues });
|
|
60
|
+
batches.push(parsed.value);
|
|
61
|
+
}
|
|
62
|
+
const received = await journal.receive(batches);
|
|
63
|
+
if (!received.ok)
|
|
64
|
+
return err(received.error);
|
|
65
|
+
return ok({
|
|
66
|
+
batches: batches.length,
|
|
67
|
+
signals: batches.reduce((count, batch) => count + batch.signals.length, 0),
|
|
68
|
+
});
|
|
69
|
+
};
|
|
70
|
+
//# sourceMappingURL=ingest.js.map
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who may post a batch, and how often.
|
|
3
|
+
*
|
|
4
|
+
* `ingest.ts` is the doorway a batch comes through and it asks one question:
|
|
5
|
+
* *is this a reader signal batch*. This module asks the other one, which no
|
|
6
|
+
* other part of Loom has ever had to ask — **is this deployment willing to pay
|
|
7
|
+
* for the answer.**
|
|
8
|
+
*
|
|
9
|
+
* Every other write in this runtime is made by a deployment's own server. A
|
|
10
|
+
* reader-signal batch is written by any browser that can reach the URL, and the
|
|
11
|
+
* table it lands in is the largest one a deployment with signals switched on
|
|
12
|
+
* will have. So the door needs arithmetic, and the arithmetic needs to be
|
|
13
|
+
* somewhere it can be read and tested without a request, a clock or a database
|
|
14
|
+
* — which is here, exactly as `throttle.ts` is that for the sign-in form.
|
|
15
|
+
*
|
|
16
|
+
* **No HTTP in this file.** Which status code each refusal deserves is the
|
|
17
|
+
* route handler's, for `ingest.ts`'s reason: the handler that serves this is a
|
|
18
|
+
* surface's, not the framework's.
|
|
19
|
+
*
|
|
20
|
+
* **What a subject is, is the caller's to decide, and it may not be an
|
|
21
|
+
* identity.** This module takes an opaque string and counts against it. 0146
|
|
22
|
+
* refuses anything that identifies a reader, and a limiter that had to be told
|
|
23
|
+
* who somebody is would be the loophole in it — so the contract is a key, and
|
|
24
|
+
* the caller is expected to hand over something that stops being meaningful the
|
|
25
|
+
* moment the counter holding it does.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* A subject the gate could not make room for.
|
|
29
|
+
*
|
|
30
|
+
* The counter is bounded, so at some number of distinct callers it stops
|
|
31
|
+
* distinguishing them, and the question is what it does then. Falling open
|
|
32
|
+
* would mean a limiter any attacker with enough addresses can switch off, which
|
|
33
|
+
* is worse than none because the deployment believes it has one. Refusing
|
|
34
|
+
* everybody takes the site down over a crowd.
|
|
35
|
+
*
|
|
36
|
+
* So they share a count, which is `subject.ts`'s answer to the same question
|
|
37
|
+
* and the direction to be wrong in: stricter than counting them separately,
|
|
38
|
+
* and it costs nothing to a deployment that never fills the map.
|
|
39
|
+
*/
|
|
40
|
+
export declare const CROWDED_SUBJECT = "crowded";
|
|
41
|
+
export type IntakePolicy = {
|
|
42
|
+
/** The largest delivery the door will read, in bytes. */
|
|
43
|
+
readonly maxBytes: number;
|
|
44
|
+
/** Deliveries one subject may make inside a window. */
|
|
45
|
+
readonly deliveries: number;
|
|
46
|
+
readonly windowMs: number;
|
|
47
|
+
/** How many subjects the counter distinguishes before {@link CROWDED_SUBJECT}. */
|
|
48
|
+
readonly subjects: number;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* `sendBeacon` is specified to refuse a body over 64 KB, so a delivery larger
|
|
52
|
+
* than that did not come from a beacon — which makes the ceiling a statement
|
|
53
|
+
* about the sender rather than a number somebody liked. `fetch` has no such
|
|
54
|
+
* limit and the fallback path is held to the same one deliberately.
|
|
55
|
+
*
|
|
56
|
+
* A broadcaster flushes every five seconds, so one page view is twelve
|
|
57
|
+
* deliveries a minute. A hundred and twenty is eight of those at once — more
|
|
58
|
+
* tabs than a reader has open on one site, and enough headroom for a queue
|
|
59
|
+
* draining after an outage, which is the case `MAX_BATCHES_PER_DELIVERY` exists
|
|
60
|
+
* to allow rather than to punish.
|
|
61
|
+
*
|
|
62
|
+
* Ten thousand subjects is about a megabyte of counters and far past the point
|
|
63
|
+
* where the traffic is an attack rather than an audience.
|
|
64
|
+
*/
|
|
65
|
+
export declare const DEFAULT_INTAKE_POLICY: IntakePolicy;
|
|
66
|
+
/**
|
|
67
|
+
* What the gate remembers about one subject: a fixed window and a count inside
|
|
68
|
+
* it. Two numbers and no identity, for `AttemptRecord`'s reason.
|
|
69
|
+
*
|
|
70
|
+
* A fixed window rather than a sliding one or a bucket, because the thing being
|
|
71
|
+
* protected is a table's growth rate over minutes and every refinement costs
|
|
72
|
+
* per-subject state that has to be held in memory for every caller. A caller
|
|
73
|
+
* who times their deliveries across a window boundary gets two windows' worth
|
|
74
|
+
* in a moment; at these numbers that is 240 deliveries and not a problem worth
|
|
75
|
+
* a data structure.
|
|
76
|
+
*/
|
|
77
|
+
export type IntakeCount = {
|
|
78
|
+
readonly deliveries: number;
|
|
79
|
+
readonly windowStartedAt: number;
|
|
80
|
+
};
|
|
81
|
+
/**
|
|
82
|
+
* `too-large` carries the count as `admitted` does, because it spent one: a
|
|
83
|
+
* caller whose body was refused has still had their delivery read far enough to
|
|
84
|
+
* refuse it. `too-often` carries none — the count that refused them is already
|
|
85
|
+
* what there is to remember.
|
|
86
|
+
*/
|
|
87
|
+
export type IntakeVerdict = {
|
|
88
|
+
readonly code: "admitted";
|
|
89
|
+
readonly count: IntakeCount;
|
|
90
|
+
} | {
|
|
91
|
+
readonly code: "too-large";
|
|
92
|
+
readonly count: IntakeCount;
|
|
93
|
+
readonly limit: number;
|
|
94
|
+
readonly given: number;
|
|
95
|
+
} | {
|
|
96
|
+
readonly code: "too-often";
|
|
97
|
+
readonly limit: number;
|
|
98
|
+
readonly retryAfterMs: number;
|
|
99
|
+
};
|
|
100
|
+
export declare const describeIntakeVerdict: (verdict: IntakeVerdict) => string;
|
|
101
|
+
/**
|
|
102
|
+
* Whether this delivery is allowed, given what the subject has already sent.
|
|
103
|
+
*
|
|
104
|
+
* Pure: no clock, no map, no request. `now` and the byte count are handed in,
|
|
105
|
+
* and the answer is a verdict and the count to remember.
|
|
106
|
+
*
|
|
107
|
+
* **The rate is decided before the size.** A caller already over their budget
|
|
108
|
+
* is told so rather than told their body was too big, because the first is the
|
|
109
|
+
* one they can act on and the second would restart their guessing. And an
|
|
110
|
+
* oversized delivery still **spends budget** — a refusal that cost the sender
|
|
111
|
+
* nothing is an endpoint that can be hammered for free.
|
|
112
|
+
*
|
|
113
|
+
* A `now` or a `bytes` that is not a finite number is treated as a fresh window
|
|
114
|
+
* and an unmeasurable body rather than trusted into the arithmetic: both arrive
|
|
115
|
+
* from outside — one from a clock, one from a header a caller wrote.
|
|
116
|
+
*/
|
|
117
|
+
export declare const admit: (count: IntakeCount | null, bytes: number, now: number, policy: IntakePolicy) => IntakeVerdict;
|
|
118
|
+
export type IntakeGate = {
|
|
119
|
+
/**
|
|
120
|
+
* The policy this gate counts by.
|
|
121
|
+
*
|
|
122
|
+
* Carried on the gate rather than left beside it, because a caller holding
|
|
123
|
+
* both had two copies that could disagree — and the one that decides is
|
|
124
|
+
* whichever the gate was built with, silently. A door has one policy.
|
|
125
|
+
*/
|
|
126
|
+
readonly policy: IntakePolicy;
|
|
127
|
+
readonly admit: (subject: string, bytes: number, now: number) => IntakeVerdict;
|
|
128
|
+
/** How many subjects are being counted. For a status endpoint, not for a decision. */
|
|
129
|
+
readonly subjects: () => number;
|
|
130
|
+
};
|
|
131
|
+
/**
|
|
132
|
+
* The counter that `admit` decides against.
|
|
133
|
+
*
|
|
134
|
+
* Its state is held inside the closure and changed in place, which is
|
|
135
|
+
* `createSignalLedger`'s arrangement and is here for the same reason: one
|
|
136
|
+
* process's private accumulator, reached by nothing else, constant time per
|
|
137
|
+
* call.
|
|
138
|
+
*
|
|
139
|
+
* **It is memory, and memory on a serverless host is per instance.** A
|
|
140
|
+
* deployment running eight instances tolerates roughly eight times the rate
|
|
141
|
+
* this policy names. That is the same caveat `attempt-log.ts` states about the
|
|
142
|
+
* sign-in throttle, and the answer is the same: a durable counter would mean a
|
|
143
|
+
* database write to decide whether to allow a database write, which is the
|
|
144
|
+
* cost this exists to bound. What must not happen is the limit silently
|
|
145
|
+
* ceasing to apply, and a bounded map that shares a count when it is full is
|
|
146
|
+
* how that is avoided.
|
|
147
|
+
*/
|
|
148
|
+
export declare const createIntakeGate: (policy?: IntakePolicy) => IntakeGate;
|
|
149
|
+
//# sourceMappingURL=intake.d.ts.map
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who may post a batch, and how often.
|
|
3
|
+
*
|
|
4
|
+
* `ingest.ts` is the doorway a batch comes through and it asks one question:
|
|
5
|
+
* *is this a reader signal batch*. This module asks the other one, which no
|
|
6
|
+
* other part of Loom has ever had to ask — **is this deployment willing to pay
|
|
7
|
+
* for the answer.**
|
|
8
|
+
*
|
|
9
|
+
* Every other write in this runtime is made by a deployment's own server. A
|
|
10
|
+
* reader-signal batch is written by any browser that can reach the URL, and the
|
|
11
|
+
* table it lands in is the largest one a deployment with signals switched on
|
|
12
|
+
* will have. So the door needs arithmetic, and the arithmetic needs to be
|
|
13
|
+
* somewhere it can be read and tested without a request, a clock or a database
|
|
14
|
+
* — which is here, exactly as `throttle.ts` is that for the sign-in form.
|
|
15
|
+
*
|
|
16
|
+
* **No HTTP in this file.** Which status code each refusal deserves is the
|
|
17
|
+
* route handler's, for `ingest.ts`'s reason: the handler that serves this is a
|
|
18
|
+
* surface's, not the framework's.
|
|
19
|
+
*
|
|
20
|
+
* **What a subject is, is the caller's to decide, and it may not be an
|
|
21
|
+
* identity.** This module takes an opaque string and counts against it. 0146
|
|
22
|
+
* refuses anything that identifies a reader, and a limiter that had to be told
|
|
23
|
+
* who somebody is would be the loophole in it — so the contract is a key, and
|
|
24
|
+
* the caller is expected to hand over something that stops being meaningful the
|
|
25
|
+
* moment the counter holding it does.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* A subject the gate could not make room for.
|
|
29
|
+
*
|
|
30
|
+
* The counter is bounded, so at some number of distinct callers it stops
|
|
31
|
+
* distinguishing them, and the question is what it does then. Falling open
|
|
32
|
+
* would mean a limiter any attacker with enough addresses can switch off, which
|
|
33
|
+
* is worse than none because the deployment believes it has one. Refusing
|
|
34
|
+
* everybody takes the site down over a crowd.
|
|
35
|
+
*
|
|
36
|
+
* So they share a count, which is `subject.ts`'s answer to the same question
|
|
37
|
+
* and the direction to be wrong in: stricter than counting them separately,
|
|
38
|
+
* and it costs nothing to a deployment that never fills the map.
|
|
39
|
+
*/
|
|
40
|
+
export const CROWDED_SUBJECT = "crowded";
|
|
41
|
+
/**
|
|
42
|
+
* `sendBeacon` is specified to refuse a body over 64 KB, so a delivery larger
|
|
43
|
+
* than that did not come from a beacon — which makes the ceiling a statement
|
|
44
|
+
* about the sender rather than a number somebody liked. `fetch` has no such
|
|
45
|
+
* limit and the fallback path is held to the same one deliberately.
|
|
46
|
+
*
|
|
47
|
+
* A broadcaster flushes every five seconds, so one page view is twelve
|
|
48
|
+
* deliveries a minute. A hundred and twenty is eight of those at once — more
|
|
49
|
+
* tabs than a reader has open on one site, and enough headroom for a queue
|
|
50
|
+
* draining after an outage, which is the case `MAX_BATCHES_PER_DELIVERY` exists
|
|
51
|
+
* to allow rather than to punish.
|
|
52
|
+
*
|
|
53
|
+
* Ten thousand subjects is about a megabyte of counters and far past the point
|
|
54
|
+
* where the traffic is an attack rather than an audience.
|
|
55
|
+
*/
|
|
56
|
+
export const DEFAULT_INTAKE_POLICY = {
|
|
57
|
+
maxBytes: 64 * 1024,
|
|
58
|
+
deliveries: 120,
|
|
59
|
+
windowMs: 60 * 1000,
|
|
60
|
+
subjects: 10_000,
|
|
61
|
+
};
|
|
62
|
+
export const describeIntakeVerdict = (verdict) => {
|
|
63
|
+
if (verdict.code === "admitted")
|
|
64
|
+
return "admitted";
|
|
65
|
+
if (verdict.code === "too-large") {
|
|
66
|
+
return `a delivery may be ${verdict.limit} bytes and this one was ${verdict.given}`;
|
|
67
|
+
}
|
|
68
|
+
return `a sender may deliver ${verdict.limit} times a window and this one has; ${verdict.retryAfterMs}ms left`;
|
|
69
|
+
};
|
|
70
|
+
const freshWindow = (now) => ({ deliveries: 1, windowStartedAt: now });
|
|
71
|
+
/**
|
|
72
|
+
* Whether this delivery is allowed, given what the subject has already sent.
|
|
73
|
+
*
|
|
74
|
+
* Pure: no clock, no map, no request. `now` and the byte count are handed in,
|
|
75
|
+
* and the answer is a verdict and the count to remember.
|
|
76
|
+
*
|
|
77
|
+
* **The rate is decided before the size.** A caller already over their budget
|
|
78
|
+
* is told so rather than told their body was too big, because the first is the
|
|
79
|
+
* one they can act on and the second would restart their guessing. And an
|
|
80
|
+
* oversized delivery still **spends budget** — a refusal that cost the sender
|
|
81
|
+
* nothing is an endpoint that can be hammered for free.
|
|
82
|
+
*
|
|
83
|
+
* A `now` or a `bytes` that is not a finite number is treated as a fresh window
|
|
84
|
+
* and an unmeasurable body rather than trusted into the arithmetic: both arrive
|
|
85
|
+
* from outside — one from a clock, one from a header a caller wrote.
|
|
86
|
+
*/
|
|
87
|
+
export const admit = (count, bytes, now, policy) => {
|
|
88
|
+
const at = Number.isFinite(now) ? now : 0;
|
|
89
|
+
const expired = count === null || at - count.windowStartedAt >= policy.windowMs || at < count.windowStartedAt;
|
|
90
|
+
if (!expired && count.deliveries >= policy.deliveries) {
|
|
91
|
+
return {
|
|
92
|
+
code: "too-often",
|
|
93
|
+
limit: policy.deliveries,
|
|
94
|
+
retryAfterMs: Math.max(0, count.windowStartedAt + policy.windowMs - at),
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
const spent = expired
|
|
98
|
+
? freshWindow(at)
|
|
99
|
+
: { deliveries: count.deliveries + 1, windowStartedAt: count.windowStartedAt };
|
|
100
|
+
/**
|
|
101
|
+
* An unmeasurable body is refused rather than admitted. The only caller that
|
|
102
|
+
* cannot say how large its delivery is, is one that chose not to.
|
|
103
|
+
*/
|
|
104
|
+
const given = Number.isFinite(bytes) && bytes >= 0 ? bytes : Number.POSITIVE_INFINITY;
|
|
105
|
+
if (given > policy.maxBytes) {
|
|
106
|
+
return { code: "too-large", count: spent, limit: policy.maxBytes, given };
|
|
107
|
+
}
|
|
108
|
+
return { code: "admitted", count: spent };
|
|
109
|
+
};
|
|
110
|
+
/**
|
|
111
|
+
* The counter that `admit` decides against.
|
|
112
|
+
*
|
|
113
|
+
* Its state is held inside the closure and changed in place, which is
|
|
114
|
+
* `createSignalLedger`'s arrangement and is here for the same reason: one
|
|
115
|
+
* process's private accumulator, reached by nothing else, constant time per
|
|
116
|
+
* call.
|
|
117
|
+
*
|
|
118
|
+
* **It is memory, and memory on a serverless host is per instance.** A
|
|
119
|
+
* deployment running eight instances tolerates roughly eight times the rate
|
|
120
|
+
* this policy names. That is the same caveat `attempt-log.ts` states about the
|
|
121
|
+
* sign-in throttle, and the answer is the same: a durable counter would mean a
|
|
122
|
+
* database write to decide whether to allow a database write, which is the
|
|
123
|
+
* cost this exists to bound. What must not happen is the limit silently
|
|
124
|
+
* ceasing to apply, and a bounded map that shares a count when it is full is
|
|
125
|
+
* how that is avoided.
|
|
126
|
+
*/
|
|
127
|
+
export const createIntakeGate = (policy = DEFAULT_INTAKE_POLICY) => {
|
|
128
|
+
const counts = new Map();
|
|
129
|
+
/** Windows that have closed hold nothing anybody is owed, so they are the first to go. */
|
|
130
|
+
const sweep = (now) => {
|
|
131
|
+
for (const [key, count] of counts) {
|
|
132
|
+
if (now - count.windowStartedAt >= policy.windowMs)
|
|
133
|
+
counts.delete(key);
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
const keyFor = (subject, now) => {
|
|
137
|
+
if (counts.has(subject) || counts.size < policy.subjects)
|
|
138
|
+
return subject;
|
|
139
|
+
sweep(now);
|
|
140
|
+
return counts.size < policy.subjects ? subject : CROWDED_SUBJECT;
|
|
141
|
+
};
|
|
142
|
+
return {
|
|
143
|
+
policy,
|
|
144
|
+
admit: (subject, bytes, now) => {
|
|
145
|
+
const key = keyFor(subject, now);
|
|
146
|
+
const verdict = admit(counts.get(key) ?? null, bytes, now, policy);
|
|
147
|
+
if (verdict.code !== "too-often")
|
|
148
|
+
counts.set(key, verdict.count);
|
|
149
|
+
return verdict;
|
|
150
|
+
},
|
|
151
|
+
subjects: () => counts.size,
|
|
152
|
+
};
|
|
153
|
+
};
|
|
154
|
+
//# sourceMappingURL=intake.js.map
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import type { TreeId } from "../ids.js";
|
|
2
|
+
import { type PageDirection, type PageEnds } from "../paging.js";
|
|
3
|
+
import type { Result } from "../result.js";
|
|
4
|
+
import type { ReaderSignalBatch } from "./signal.js";
|
|
5
|
+
/**
|
|
6
|
+
* Where batches wait to be rolled up.
|
|
7
|
+
*
|
|
8
|
+
* This is a **buffer, not an archive**, and everything about it follows from
|
|
9
|
+
* that. Aggregates are the durable artefact (0146); raw batches exist for as
|
|
10
|
+
* long as it takes rollup to read them and no longer. A deployment that kept
|
|
11
|
+
* them would hold the largest table in its database in order to answer
|
|
12
|
+
* questions that are all about counters.
|
|
13
|
+
*
|
|
14
|
+
* It is deliberately the same shape as `src/telemetry/journal.ts` — append,
|
|
15
|
+
* page by an opaque cursor, forget a prefix — because a second paged log that
|
|
16
|
+
* paged differently would be a second thing to learn and a second place for the
|
|
17
|
+
* cursor rules to be subtly wrong. What it is not is the same *table*: a
|
|
18
|
+
* journal holds what the runtime said about itself, and this holds what
|
|
19
|
+
* browsers said about pages, and the two have different retention and different
|
|
20
|
+
* volumes by two orders of magnitude.
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* The only way it fails. No `not-found` — reading a tree nothing has been
|
|
24
|
+
* received about is an empty page, because a buffer makes no claim that a tree
|
|
25
|
+
* exists. No conflict — receiving a batch cannot collide with another batch.
|
|
26
|
+
*/
|
|
27
|
+
export type ReaderSignalStoreError = {
|
|
28
|
+
readonly code: "unavailable";
|
|
29
|
+
readonly detail: string;
|
|
30
|
+
};
|
|
31
|
+
export declare const describeReaderSignalStoreError: (error: ReaderSignalStoreError) => string;
|
|
32
|
+
/**
|
|
33
|
+
* A batch as it comes back out, with the position the buffer gave it.
|
|
34
|
+
*
|
|
35
|
+
* `seq` orders by arrival, not by `sentAt`. A browser's clock is not merely
|
|
36
|
+
* skewed but attacker-controlled — `sentAt` is a number a page said — so it can
|
|
37
|
+
* order nothing and can certainly not be what retention measures. `receivedAt`
|
|
38
|
+
* is stamped here and is the only timestamp the buffer vouches for.
|
|
39
|
+
*/
|
|
40
|
+
export type ReceivedBatch = ReaderSignalBatch & {
|
|
41
|
+
readonly seq: number;
|
|
42
|
+
readonly receivedAt: string;
|
|
43
|
+
};
|
|
44
|
+
export type ReaderSignalReadRequest = {
|
|
45
|
+
/** Absent reads every tree the handle can see, which is the scope rule (0020). */
|
|
46
|
+
readonly treeId?: TreeId;
|
|
47
|
+
/** A cursor from a previous page's `older`/`newer`, passed back unread. */
|
|
48
|
+
readonly cursor?: string;
|
|
49
|
+
/** Default `newer`, which with no cursor is the oldest page — where rollup starts. */
|
|
50
|
+
readonly direction?: PageDirection;
|
|
51
|
+
readonly limit?: number;
|
|
52
|
+
};
|
|
53
|
+
export type ReaderSignalPage = PageEnds & {
|
|
54
|
+
/** Always ascending by `seq`, whichever end the page was taken from. */
|
|
55
|
+
readonly batches: readonly ReceivedBatch[];
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Larger than a telemetry page, because these are read only to be folded and a
|
|
59
|
+
* batch is small. Rollup walks the whole window, so the page size is purely how
|
|
60
|
+
* much of it is in memory at once.
|
|
61
|
+
*/
|
|
62
|
+
export declare const DEFAULT_READER_SIGNAL_LIMIT = 500;
|
|
63
|
+
export declare const MAX_READER_SIGNAL_LIMIT = 2000;
|
|
64
|
+
export declare const clampReaderSignalLimit: (limit: number | undefined) => number;
|
|
65
|
+
/**
|
|
66
|
+
* What the buffer is asked to forget, as a position rather than a rule.
|
|
67
|
+
*
|
|
68
|
+
* Declared here rather than shared with telemetry's identical pair on purpose.
|
|
69
|
+
* They are the same two fields today and they answer to different policies —
|
|
70
|
+
* telemetry must not cut an episode in half, and this must not forget a batch
|
|
71
|
+
* that has not been rolled up — so a shared type would be two subsystems
|
|
72
|
+
* agreeing by coincidence and discovering it when one of them changes.
|
|
73
|
+
*/
|
|
74
|
+
export type ForgetBefore = {
|
|
75
|
+
readonly before: number;
|
|
76
|
+
};
|
|
77
|
+
export type ForgetOutcome = {
|
|
78
|
+
readonly removed: number;
|
|
79
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* Three operations, mirroring the journal's.
|
|
82
|
+
*
|
|
83
|
+
* `receive` takes several batches because an ingestion endpoint may be handed
|
|
84
|
+
* several and should pay for one round trip. Unlike a journal's, this batch has
|
|
85
|
+
* no atomicity to protect — signals are independent observations and half of
|
|
86
|
+
* them is a smaller sample rather than a broken story — but a single statement
|
|
87
|
+
* is how both implementations write anyway.
|
|
88
|
+
*/
|
|
89
|
+
export interface ReaderSignalJournal {
|
|
90
|
+
readonly receive: (batches: readonly ReaderSignalBatch[]) => Promise<Result<void, ReaderSignalStoreError>>;
|
|
91
|
+
readonly read: (request?: ReaderSignalReadRequest) => Promise<Result<ReaderSignalPage, ReaderSignalStoreError>>;
|
|
92
|
+
readonly forget: (request: ForgetBefore) => Promise<Result<ForgetOutcome, ReaderSignalStoreError>>;
|
|
93
|
+
}
|
|
94
|
+
//# sourceMappingURL=journal.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { clampLimit } from "../paging.js";
|
|
2
|
+
export const describeReaderSignalStoreError = (error) => `reader signals are unavailable: ${error.detail}`;
|
|
3
|
+
/**
|
|
4
|
+
* Larger than a telemetry page, because these are read only to be folded and a
|
|
5
|
+
* batch is small. Rollup walks the whole window, so the page size is purely how
|
|
6
|
+
* much of it is in memory at once.
|
|
7
|
+
*/
|
|
8
|
+
export const DEFAULT_READER_SIGNAL_LIMIT = 500;
|
|
9
|
+
export const MAX_READER_SIGNAL_LIMIT = 2000;
|
|
10
|
+
export const clampReaderSignalLimit = (limit) => clampLimit(limit, { fallback: DEFAULT_READER_SIGNAL_LIMIT, max: MAX_READER_SIGNAL_LIMIT });
|
|
11
|
+
//# sourceMappingURL=journal.js.map
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four kinds of reader signal, with nothing else in the module.
|
|
3
|
+
*
|
|
4
|
+
* The schema in `signal.ts` is built from this list. It lives apart so the
|
|
5
|
+
* broadcaster, which runs in a visitor's browser, can know the kinds without
|
|
6
|
+
* pulling in the schema library (0136).
|
|
7
|
+
*/
|
|
8
|
+
export declare const READER_SIGNAL_KINDS: readonly ["viewed", "dwelled", "activated", "disclosed"];
|
|
9
|
+
/**
|
|
10
|
+
* The kinds whose node is not the thing a reader aimed at.
|
|
11
|
+
*
|
|
12
|
+
* A reader presses a button and opens a disclosure; both are addressed nodes of
|
|
13
|
+
* their own, so the node such a signal is filed against is the control rather
|
|
14
|
+
* than the region the control is in. `viewed` and `dwelled` have no such gap —
|
|
15
|
+
* they are observed on the addressed element itself — which is why these two
|
|
16
|
+
* carry an ancestry and the other two do not.
|
|
17
|
+
*
|
|
18
|
+
* Here rather than in `signal.ts` so the broadcaster can know which signals it
|
|
19
|
+
* must walk for without loading the schema library (0136).
|
|
20
|
+
*/
|
|
21
|
+
export declare const DELEGATED_READER_SIGNAL_KINDS: readonly ["activated", "disclosed"];
|
|
22
|
+
//# sourceMappingURL=kinds.d.ts.map
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The four kinds of reader signal, with nothing else in the module.
|
|
3
|
+
*
|
|
4
|
+
* The schema in `signal.ts` is built from this list. It lives apart so the
|
|
5
|
+
* broadcaster, which runs in a visitor's browser, can know the kinds without
|
|
6
|
+
* pulling in the schema library (0136).
|
|
7
|
+
*/
|
|
8
|
+
export const READER_SIGNAL_KINDS = ["viewed", "dwelled", "activated", "disclosed"];
|
|
9
|
+
/**
|
|
10
|
+
* The kinds whose node is not the thing a reader aimed at.
|
|
11
|
+
*
|
|
12
|
+
* A reader presses a button and opens a disclosure; both are addressed nodes of
|
|
13
|
+
* their own, so the node such a signal is filed against is the control rather
|
|
14
|
+
* than the region the control is in. `viewed` and `dwelled` have no such gap —
|
|
15
|
+
* they are observed on the addressed element itself — which is why these two
|
|
16
|
+
* carry an ancestry and the other two do not.
|
|
17
|
+
*
|
|
18
|
+
* Here rather than in `signal.ts` so the broadcaster can know which signals it
|
|
19
|
+
* must walk for without loading the schema library (0136).
|
|
20
|
+
*/
|
|
21
|
+
export const DELEGATED_READER_SIGNAL_KINDS = ["activated", "disclosed"];
|
|
22
|
+
//# sourceMappingURL=kinds.js.map
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { PrimitiveType } from "../primitive-type.js";
|
|
3
|
+
import type { ReaderSignal } from "./signal.js";
|
|
4
|
+
/**
|
|
5
|
+
* The bookkeeping behind a broadcast, with no browser in it.
|
|
6
|
+
*
|
|
7
|
+
* Everything the broadcaster observes arrives here as a plain call with a
|
|
8
|
+
* timestamp — this node came on screen, that one left, the tab was hidden — and
|
|
9
|
+
* everything it sends leaves as the signals `drain` returns. Keeping the
|
|
10
|
+
* arithmetic out of the DOM code is what lets the one part that can be wrong in
|
|
11
|
+
* a subtle way (time counted twice, or counted while nobody was looking) be
|
|
12
|
+
* tested exactly.
|
|
13
|
+
*
|
|
14
|
+
* **Its state is held inside the ledger and changed in place.** A ledger that
|
|
15
|
+
* returned a fresh copy on every call was the first version, and it cost the
|
|
16
|
+
* square of the page: every node seen for the first time copied the set of every
|
|
17
|
+
* node seen before it, so scrolling a 6,000-node page took twelve times as long
|
|
18
|
+
* as a 1,000-node one rather than six. A ledger is one broadcaster's private
|
|
19
|
+
* accumulator, reached by nothing else, which is the same shape
|
|
20
|
+
* `collectTelemetry` holds its buffer in — the state is contained, and every
|
|
21
|
+
* call is constant time.
|
|
22
|
+
*/
|
|
23
|
+
export type SignalAddress = {
|
|
24
|
+
readonly nodeId: NodeId;
|
|
25
|
+
readonly type: PrimitiveType;
|
|
26
|
+
};
|
|
27
|
+
export type SignalLedger = {
|
|
28
|
+
/** A node came into view. The first time it is seen while the page is visible, it is also `viewed`. */
|
|
29
|
+
readonly entered: (address: SignalAddress, now: number) => void;
|
|
30
|
+
readonly left: (nodeId: NodeId, now: number) => void;
|
|
31
|
+
/** Something a reader did, queued as it happened. */
|
|
32
|
+
readonly noted: (signal: ReaderSignal) => void;
|
|
33
|
+
/** The page stopped being looked at. Open stretches close; the nodes stay on screen. */
|
|
34
|
+
readonly hid: (now: number) => void;
|
|
35
|
+
/** The page is looked at again. What is on screen starts counting, and is viewed if it never was. */
|
|
36
|
+
readonly showed: (now: number) => void;
|
|
37
|
+
/**
|
|
38
|
+
* Everything owed since the last drain. Open stretches are cut at `now` and
|
|
39
|
+
* restarted from it, so a node that stays on screen across many batches is
|
|
40
|
+
* counted once per millisecond, in whichever batch that millisecond fell.
|
|
41
|
+
* Sub-millisecond remainders are dropped: a `dwelled` must be a whole number.
|
|
42
|
+
*/
|
|
43
|
+
readonly drain: (now: number) => readonly ReaderSignal[];
|
|
44
|
+
};
|
|
45
|
+
export declare const createSignalLedger: (hiddenAtStart?: boolean) => SignalLedger;
|
|
46
|
+
//# sourceMappingURL=ledger.d.ts.map
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
export const createSignalLedger = (hiddenAtStart = false) => {
|
|
2
|
+
const onScreen = new Map();
|
|
3
|
+
const seen = new Set();
|
|
4
|
+
const dwell = new Map();
|
|
5
|
+
let queued = [];
|
|
6
|
+
let hidden = hiddenAtStart;
|
|
7
|
+
const accrue = (entry, now) => {
|
|
8
|
+
if (entry.since === null || now <= entry.since)
|
|
9
|
+
return;
|
|
10
|
+
const total = dwell.get(entry.address.nodeId);
|
|
11
|
+
if (total === undefined)
|
|
12
|
+
dwell.set(entry.address.nodeId, { address: entry.address, ms: now - entry.since });
|
|
13
|
+
else
|
|
14
|
+
total.ms += now - entry.since;
|
|
15
|
+
};
|
|
16
|
+
/** Only ever while visible: a node on screen in a tab nobody is looking at has not been viewed. */
|
|
17
|
+
const sighted = (address, now) => {
|
|
18
|
+
if (seen.has(address.nodeId))
|
|
19
|
+
return;
|
|
20
|
+
seen.add(address.nodeId);
|
|
21
|
+
queued.push({ kind: "viewed", ...address, at: now });
|
|
22
|
+
};
|
|
23
|
+
return {
|
|
24
|
+
entered: (address, now) => {
|
|
25
|
+
if (onScreen.has(address.nodeId))
|
|
26
|
+
return;
|
|
27
|
+
onScreen.set(address.nodeId, { address, since: hidden ? null : now });
|
|
28
|
+
if (!hidden)
|
|
29
|
+
sighted(address, now);
|
|
30
|
+
},
|
|
31
|
+
left: (nodeId, now) => {
|
|
32
|
+
const entry = onScreen.get(nodeId);
|
|
33
|
+
if (entry === undefined)
|
|
34
|
+
return;
|
|
35
|
+
accrue(entry, now);
|
|
36
|
+
onScreen.delete(nodeId);
|
|
37
|
+
},
|
|
38
|
+
noted: (signal) => {
|
|
39
|
+
queued.push(signal);
|
|
40
|
+
},
|
|
41
|
+
hid: (now) => {
|
|
42
|
+
if (hidden)
|
|
43
|
+
return;
|
|
44
|
+
hidden = true;
|
|
45
|
+
for (const entry of onScreen.values()) {
|
|
46
|
+
accrue(entry, now);
|
|
47
|
+
entry.since = null;
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
showed: (now) => {
|
|
51
|
+
if (!hidden)
|
|
52
|
+
return;
|
|
53
|
+
hidden = false;
|
|
54
|
+
for (const entry of onScreen.values()) {
|
|
55
|
+
entry.since = now;
|
|
56
|
+
sighted(entry.address, now);
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
drain: (now) => {
|
|
60
|
+
if (queued.length === 0 && dwell.size === 0 && (hidden || onScreen.size === 0))
|
|
61
|
+
return [];
|
|
62
|
+
if (!hidden) {
|
|
63
|
+
for (const entry of onScreen.values()) {
|
|
64
|
+
accrue(entry, now);
|
|
65
|
+
entry.since = now;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
const dwelled = [];
|
|
69
|
+
for (const { address, ms } of dwell.values()) {
|
|
70
|
+
const whole = Math.floor(ms);
|
|
71
|
+
if (whole > 0)
|
|
72
|
+
dwelled.push({ kind: "dwelled", ...address, ms: whole });
|
|
73
|
+
}
|
|
74
|
+
const signals = queued.length === 0 ? dwelled : [...queued, ...dwelled];
|
|
75
|
+
queued = [];
|
|
76
|
+
dwell.clear();
|
|
77
|
+
return signals;
|
|
78
|
+
},
|
|
79
|
+
};
|
|
80
|
+
};
|
|
81
|
+
//# sourceMappingURL=ledger.js.map
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type Clock } from "../runtime/events.js";
|
|
2
|
+
import { type ReaderSignalJournal } from "./journal.js";
|
|
3
|
+
import type { ReaderTallyStore } from "./tally.js";
|
|
4
|
+
/**
|
|
5
|
+
* The buffer and the counters, in the process.
|
|
6
|
+
*
|
|
7
|
+
* Like the memory journal and the memory store, these are the reference
|
|
8
|
+
* implementations rather than test doubles: the contract suite is written
|
|
9
|
+
* against what they do, and Postgres is checked against the same suite.
|
|
10
|
+
*
|
|
11
|
+
* The clock is a parameter for the reason it is one everywhere else — a
|
|
12
|
+
* `receivedAt` read off the wall clock makes every retention test a race
|
|
13
|
+
* against real time.
|
|
14
|
+
*/
|
|
15
|
+
export declare const memoryReaderSignalJournal: (clock?: Clock) => ReaderSignalJournal;
|
|
16
|
+
export declare const memoryReaderTallyStore: () => ReaderTallyStore;
|
|
17
|
+
//# sourceMappingURL=memory.d.ts.map
|