@fungi.computer/oyster 0.24.0 → 0.25.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.
@@ -0,0 +1,169 @@
1
+ <!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
2
+
3
+ [**@fungi.computer/oyster**](../README.md)
4
+
5
+ ---
6
+
7
+ [@fungi.computer/oyster](../modules.md) / browser/boot-once
8
+
9
+ # browser/boot-once
10
+
11
+ ## Type Aliases
12
+
13
+ ### BootRunKey
14
+
15
+ ```ts
16
+ type BootRunKey = Readonly<{
17
+ releaseId: string;
18
+ checkVersion: string;
19
+ }>;
20
+ ```
21
+
22
+ One Release and the version of the check that judges it.
23
+
24
+ ---
25
+
26
+ ### NotCheckedCode
27
+
28
+ ```ts
29
+ type NotCheckedCode = Extract<
30
+ UiBootCheckOutcome,
31
+ {
32
+ kind: "not_checked";
33
+ }
34
+ >["code"];
35
+ ```
36
+
37
+ Why a check could not judge the page.
38
+
39
+ ---
40
+
41
+ ### BootRunClaim
42
+
43
+ ```ts
44
+ type BootRunClaim =
45
+ | Readonly<{
46
+ kind: "acquired";
47
+ }>
48
+ | Readonly<{
49
+ kind: "held";
50
+ }>
51
+ | Readonly<{
52
+ kind: "cooling";
53
+ code: NotCheckedCode;
54
+ }>;
55
+ ```
56
+
57
+ What an ask for the key's run slot learns.
58
+
59
+ ---
60
+
61
+ ### BootRunClaims
62
+
63
+ ```ts
64
+ type BootRunClaims = Readonly<{
65
+ acquire: (input) => Promise<BootRunClaim>;
66
+ finish: (input) => Promise<void>;
67
+ }>;
68
+ ```
69
+
70
+ The run slot for one key, in a store every isolate shares (the Hub's catalog
71
+ D1). `acquire` is one atomic step: it hands the slot to exactly one asker unless
72
+ a live claim exists, and a claim past its lease is free, so a crashed holder
73
+ never blocks the Release.
74
+
75
+ ---
76
+
77
+ ### SingleFlightBootInput
78
+
79
+ ```ts
80
+ type SingleFlightBootInput = BootRunKey &
81
+ Readonly<{
82
+ claims: BootRunClaims;
83
+ recorded: () => Promise<UiBootCheckOutcome | null>;
84
+ run: () => Promise<UiBootCheckOutcome>;
85
+ record: (outcome) => Promise<UiBootCheckOutcome>;
86
+ now: () => number;
87
+ sleep: (ms) => Promise<void>;
88
+ newClaimId: () => string;
89
+ leaseMs: number;
90
+ pollMs: number;
91
+ coolMs: number;
92
+ maxWaitMs: number;
93
+ }>;
94
+ ```
95
+
96
+ Everything one single-flight boot ask needs.
97
+
98
+ ## Functions
99
+
100
+ ### singleFlightBoot()
101
+
102
+ ```ts
103
+ function singleFlightBoot(input): Promise<
104
+ | {
105
+ kind: "passed";
106
+ }
107
+ | {
108
+ kind: "failed";
109
+ code: "ui_mount_failed";
110
+ diagnostics?: {
111
+ failedPredicate:
112
+ | "unexpected_candidate_request"
113
+ | "response_status"
114
+ | "request_failed"
115
+ | "page_error"
116
+ | "candidate_not_mounted";
117
+ errorName?:
118
+ | "Error"
119
+ | "TypeError"
120
+ | "RangeError"
121
+ | "SyntaxError"
122
+ | "AbortError"
123
+ | "TimeoutError"
124
+ | "Other";
125
+ finalUrlPath: string;
126
+ consoleErrors: string[];
127
+ pageErrors: string[];
128
+ failedRequests: object[];
129
+ droppedCount: number;
130
+ };
131
+ }
132
+ | {
133
+ kind: "not_checked";
134
+ code:
135
+ | "boot_runner_unavailable"
136
+ | "boot_browser_binding_missing"
137
+ | "boot_clone_unavailable"
138
+ | "boot_timeout"
139
+ | "boot_cleanup_failed"
140
+ | "ui_check_not_run_on_host";
141
+ }
142
+ >;
143
+ ```
144
+
145
+ At most one boot check per Release and check version is in flight across every
146
+ caller sharing `claims`. A definitive outcome is recorded and read by everyone
147
+ after. A waiter reuses whatever the holder produced: the recorded verdict, or
148
+ its inconclusive reason for `coolMs`. An inconclusive outcome is never a verdict
149
+ and never reported as a pass; once the cooldown ends the next ask checks again.
150
+
151
+ #### Parameters
152
+
153
+ | Parameter | Type |
154
+ | --------- | ------------------------------------------------- |
155
+ | `input` | [`SingleFlightBootInput`](#singleflightbootinput) |
156
+
157
+ #### Returns
158
+
159
+ `Promise`\< \| \{ `kind`: `"passed"`; \} \| \{ `kind`: `"failed"`; `code`:
160
+ `"ui_mount_failed"`; `diagnostics?`: \{ `failedPredicate`: \|
161
+ `"unexpected_candidate_request"` \| `"response_status"` \| `"request_failed"` \|
162
+ `"page_error"` \| `"candidate_not_mounted"`; `errorName?`: \| `"Error"` \|
163
+ `"TypeError"` \| `"RangeError"` \| `"SyntaxError"` \| `"AbortError"` \|
164
+ `"TimeoutError"` \| `"Other"`; `finalUrlPath`: `string`; `consoleErrors`:
165
+ `string`[]; `pageErrors`: `string`[]; `failedRequests`: `object`[];
166
+ `droppedCount`: `number`; \}; \} \| \{ `kind`: `"not_checked"`; `code`: \|
167
+ `"boot_runner_unavailable"` \| `"boot_browser_binding_missing"` \|
168
+ `"boot_clone_unavailable"` \| `"boot_timeout"` \| `"boot_cleanup_failed"` \|
169
+ `"ui_check_not_run_on_host"`; \}\>