priority-axi 0.1.0 → 0.2.1

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,124 @@
1
+ // update, add-line and update-line: change a record that exists. Each checks
2
+ // its fields against the index and sends one request, which inside Comis the
3
+ // Gate holds for the owner's approval. A record is named by its key in the
4
+ // path, NAME('KEY'), the only form the Gate's record type takes.
5
+ import { serviceRoot } from '../config.js';
6
+ import { usage } from '../errors.js';
7
+ import { send } from '../http.js';
8
+ import { resolveScreen, resolveSub, } from '../index/build.js';
9
+ import { recordSegment } from '../odata.js';
10
+ import { defaultColumns, tableRow } from '../output/shape.js';
11
+ import { render } from '../output/toon.js';
12
+ import { open, screenIndex, shellWord, strings, tokenLine } from './common.js';
13
+ import { assign } from './create.js';
14
+ function fields(type, where, terms) {
15
+ const body = {};
16
+ for (const term of terms)
17
+ assign(type, where, body, term);
18
+ if (!Object.keys(body).length)
19
+ throw usage('Nothing to change: give --set FIELD=VALUE.');
20
+ for (const key of type.key)
21
+ if (key in body)
22
+ throw usage(`${key} names the record; an update cannot change it.`);
23
+ return body;
24
+ }
25
+ function keyOf(input, at, what) {
26
+ const key = input.positionals[at] ?? '';
27
+ if (!key)
28
+ throw usage(`Give ${what}.`);
29
+ return key;
30
+ }
31
+ async function write(input, s, w, command) {
32
+ const root = new URL(serviceRoot(s.settings)).pathname;
33
+ if (input.values['dry-run'] === true) {
34
+ return render({
35
+ dry_run: true,
36
+ request: `${w.method} ${root}/${w.path}`,
37
+ body: w.body,
38
+ transactions: 1,
39
+ }, [
40
+ `Run \`${tokenLine(command, input.tokens, ['dry-run'])}\` to send it; inside Comis the owner approves it first`,
41
+ ]);
42
+ }
43
+ // Sent once. A write is never retried; a held write is waited on with comis action wait.
44
+ const answer = await send(s.settings, {
45
+ method: w.method,
46
+ path: w.path,
47
+ body: w.body,
48
+ context: { screen: w.screen.name },
49
+ }, input.io.http);
50
+ const record = answer.json &&
51
+ typeof answer.json === 'object' &&
52
+ !Array.isArray(answer.json)
53
+ ? answer.json
54
+ : undefined;
55
+ return render({
56
+ [w.done]: w.screen.name,
57
+ request: `${w.method} ${root}/${w.path}`,
58
+ transactions: 1,
59
+ record: record
60
+ ? tableRow(w.shown, record, defaultColumns(w.shown, [record]), 500)
61
+ : null,
62
+ }, [
63
+ `Run \`priority-axi show ${w.screen.name} ${shellWord(keyOf(input, 1, 'the key'))} --with <SUB>\` to read it back`,
64
+ ]);
65
+ }
66
+ /** update <SCREEN> <key> --set F=V: change fields of one record. */
67
+ export async function update(input) {
68
+ const s = open(input);
69
+ const { index } = await screenIndex(s);
70
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
71
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
72
+ const body = fields(screen.type, screen.name, strings(input.values.set));
73
+ return write(input, s, {
74
+ method: 'PATCH',
75
+ screen,
76
+ path: recordSegment(screen.name, screen.type, key),
77
+ body,
78
+ shown: screen.type,
79
+ done: 'updated',
80
+ }, 'update');
81
+ }
82
+ /** add-line <SCREEN> <key> <SUB> <F=V>...: add one line to a record. */
83
+ export async function addLine(input) {
84
+ const s = open(input);
85
+ const { index } = await screenIndex(s);
86
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
87
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
88
+ const sub = resolveSub(index, screen, keyOf(input, 2, 'the sub-screen after the key'));
89
+ if (!sub.many)
90
+ throw usage(`${screen.name} > ${sub.name} holds one record; change it with update-line.`);
91
+ const where = `${screen.name} > ${sub.name}`;
92
+ const body = {};
93
+ for (const term of input.positionals.slice(3))
94
+ assign(sub.def, where, body, term);
95
+ if (!Object.keys(body).length)
96
+ throw usage(`Give the new line's fields after ${sub.name}, as FIELD=VALUE.`);
97
+ return write(input, s, {
98
+ method: 'POST',
99
+ screen,
100
+ path: `${recordSegment(screen.name, screen.type, key)}/${sub.nav}`,
101
+ body,
102
+ shown: sub.def,
103
+ done: 'added',
104
+ }, 'add-line');
105
+ }
106
+ /** update-line <SCREEN> <key> <SUB> <line-key> --set F=V: change one line. */
107
+ export async function updateLine(input) {
108
+ const s = open(input);
109
+ const { index } = await screenIndex(s);
110
+ const screen = resolveScreen(index, input.positionals[0] ?? '');
111
+ const key = keyOf(input, 1, `the key of the ${screen.name} record after the screen`);
112
+ const sub = resolveSub(index, screen, keyOf(input, 2, 'the sub-screen after the key'));
113
+ const line = keyOf(input, 3, `the line's key after ${sub.name}, such as ${sub.def.key.map((k) => `${k}=1`).join(',') || 'its number'}`);
114
+ const where = `${screen.name} > ${sub.name}`;
115
+ const body = fields(sub.def, where, strings(input.values.set));
116
+ return write(input, s, {
117
+ method: 'PATCH',
118
+ screen,
119
+ path: `${recordSegment(screen.name, screen.type, key)}/${recordSegment(sub.nav, sub.def, sub.def.key.length === 1 ? line.replace(new RegExp(`^${sub.def.key[0]}=`, 'i'), '') : line, true)}`,
120
+ body,
121
+ shown: sub.def,
122
+ done: 'updated',
123
+ }, 'update-line');
124
+ }
package/dist/config.js CHANGED
@@ -63,13 +63,23 @@ export function readSettings(env, flags = {}) {
63
63
  if (user.includes(':') || /\p{Cc}/u.test(user)) {
64
64
  throw usage('The username (--user or PRIORITY_USER) must not contain a colon or control characters.');
65
65
  }
66
- return {
66
+ const settings = {
67
67
  origin,
68
68
  ini: segment(ini, 'The ini (--ini or PRIORITY_INI)'),
69
69
  company: segment(company, 'The company (--company or PRIORITY_COMPANY)'),
70
70
  user,
71
71
  password,
72
72
  };
73
+ // Comis sets COMIS_DEADLINE for every shell call; the command is killed then.
74
+ const deadline = env.COMIS_DEADLINE;
75
+ if (deadline !== undefined && deadline !== '') {
76
+ const n = Number(deadline);
77
+ if (!/^[1-9][0-9]*$/.test(deadline) || !Number.isSafeInteger(n)) {
78
+ throw usage('COMIS_DEADLINE must be a time in epoch milliseconds, a positive whole number.');
79
+ }
80
+ settings.deadline = n;
81
+ }
82
+ return settings;
73
83
  }
74
84
  export function serviceRoot(settings) {
75
85
  return `${settings.origin}/odata/Priority/${settings.ini}/${settings.company}`;
package/dist/errors.js CHANGED
@@ -3,6 +3,11 @@
3
3
  export class AxiError extends Error {
4
4
  code;
5
5
  fields;
6
+ /**
7
+ * The lowest line of a deep-insert body that Priority's form errors name
8
+ * ("שורה 2-" or "Line 2-"; line 1 is the record itself). Not printed.
9
+ */
10
+ formLine;
6
11
  constructor(code, message, fields = {}) {
7
12
  super(message);
8
13
  this.name = 'AxiError';
@@ -74,6 +79,19 @@ function interfaceErrors(json, text) {
74
79
  .map((m) => xmlText(m[1] ?? '').trim())
75
80
  .filter(Boolean);
76
81
  }
82
+ // Priority numbers the lines of a deep insert from 1, the record itself, and
83
+ // starts each form error with its line: "שורה 2- ..." or "Line 2- ...".
84
+ const FORM_LINE = /^(?:שורה|Line)\s*(\d+)\s*-/i;
85
+ /** The lowest line number Priority's form errors name, if every error names one. */
86
+ export function formLine(json, text) {
87
+ const lines = interfaceErrors(json, text).map((t) => {
88
+ const m = FORM_LINE.exec(t);
89
+ return m ? Number(m[1]) : Number.NaN;
90
+ });
91
+ if (!lines.length || lines.some((n) => !Number.isSafeInteger(n)))
92
+ return undefined;
93
+ return Math.min(...lines);
94
+ }
77
95
  /** Priority's own words: an OData error message, or its form errors. */
78
96
  export function priorityMessage(json, text) {
79
97
  const error = json && typeof json === 'object'
@@ -93,6 +111,7 @@ const GATE_REFUSALS = {
93
111
  secret_response: "The Gate withheld Priority's answer because it carried a credential.",
94
112
  body_forgotten: 'The Gate no longer holds the body of this request. Run the command again only if the owner asks.',
95
113
  out_of_budget: 'The Gate refused this request: the spending budget is used up.',
114
+ policy_refused: 'The Gate refused this request: this workbench may not send it. A reader workbench cannot write; ask the main agent to do it.',
96
115
  };
97
116
  export function classify(answer, ctx = {}) {
98
117
  const { status, headers, json } = answer;
@@ -113,7 +132,7 @@ export function classify(answer, ctx = {}) {
113
132
  }
114
133
  const message = priorityMessage(json, answer.text);
115
134
  if (status === 401) {
116
- return new AxiError('auth_failed', 'Priority rejected the username or password. Check PRIORITY_USER and PRIORITY_PASSWORD.');
135
+ return new AxiError('auth_failed', 'Priority rejected the username or password. Do not retry: after 3 failed sign-ins Priority locks the API user for 30 minutes. Check PRIORITY_USER and PRIORITY_PASSWORD with the owner first.');
117
136
  }
118
137
  if (status === 400 && message && NOT_ENABLED.some((rx) => rx.test(message))) {
119
138
  const name = ctx.screen ?? 'this screen';
@@ -128,22 +147,36 @@ export function classify(answer, ctx = {}) {
128
147
  if (status === 400 && message && BAD_COMPANY.some((rx) => rx.test(message))) {
129
148
  return new AxiError('company_not_found', `Priority does not know company ${ctx.company ?? 'given'}. Check the company code with the owner.`, { priority: message });
130
149
  }
150
+ const said = message ? { priority: message } : {};
151
+ const write = ctx.method !== undefined && ctx.method !== 'GET';
131
152
  if (status === 404) {
132
- return new AxiError('not_found', ctx.screen
133
- ? `Priority has no ${ctx.screen}. Check the name with \`priority-axi screens\`.`
134
- : 'Priority answered 404 Not Found.', screen);
153
+ return new AxiError('not_found', write
154
+ ? `Priority found no such ${ctx.screen ? `${ctx.screen} record or line` : 'record'} (404). Check the key with \`priority-axi show ${ctx.screen ?? '<SCREEN>'} <key>\`.`
155
+ : ctx.screen
156
+ ? `Priority has no ${ctx.screen}. Check the name with \`priority-axi screens\`.`
157
+ : 'Priority answered 404 Not Found.', { ...screen, ...said });
135
158
  }
136
159
  if (status === 409) {
137
- return new AxiError('already_exists', 'Priority says this record already exists. Read it instead of creating it.', { ...screen, ...(message ? { priority: message } : {}) });
160
+ if (ctx.method === 'PATCH') {
161
+ return new AxiError('priority_rejected', `Priority refused the change as a conflict (409)${message ? `: ${message.replace(/[.!?]?$/, '.')}` : '.'} Read the record with \`priority-axi show\` before changing it again.`, { ...screen, status, ...said });
162
+ }
163
+ return new AxiError('already_exists', 'Priority says this record already exists. Read it with `priority-axi show` instead of creating it again.', { ...screen, ...said });
138
164
  }
139
165
  if (status === 429) {
140
- return new AxiError('rate_limited', 'Priority is limiting requests. Wait a minute, then try again.');
166
+ const after = headers.get('retry-after');
167
+ return new AxiError('rate_limited', after
168
+ ? 'Priority is limiting requests. Wait a minute, then try again.'
169
+ : 'Priority is limiting requests, or it has locked the API user after failed sign-ins (Priority 26.1 and later lock it for 30 minutes). Wait before trying again, and do not retry in a loop.');
141
170
  }
142
171
  if (status === 501) {
143
172
  return new AxiError('unsupported_query', `Priority cannot run this query: ${message ?? 'not supported'}. Use the --where operators =, !=, >, >=, < and <=.`, screen);
144
173
  }
145
174
  if (status >= 400 && status < 500) {
146
- return new AxiError('priority_rejected', message ?? `Priority answered ${status} with no message.`, { ...screen, status });
175
+ const rejected = new AxiError('priority_rejected', message ?? `Priority answered ${status} with no message.`, { ...screen, status });
176
+ const line = formLine(json, answer.text);
177
+ if (line !== undefined)
178
+ rejected.formLine = line;
179
+ return rejected;
147
180
  }
148
181
  return new AxiError('priority_error', message ?? `Priority answered ${status} with no message.`, { ...screen, status });
149
182
  }
package/dist/http.js CHANGED
@@ -4,9 +4,14 @@
4
4
  import { serviceRoot } from './config.js';
5
5
  import { AxiError, classify } from './errors.js';
6
6
  import { VERSION } from './version.js';
7
- export const READ_TIMEOUT_MS = 90_000;
7
+ /** Priority Cloud drops a request after 3 minutes; an unfiltered document read took 86 s live. */
8
+ export const READ_TIMEOUT_MS = 150_000;
8
9
  /** Longer than the Gate's 45 s approval hold. */
9
10
  export const WRITE_TIMEOUT_MS = 120_000;
11
+ /** A write needs the Gate's 45 s approval hold and Priority's answer. */
12
+ export const WRITE_MIN_MS = 50_000;
13
+ /** Priority caps an answer at 350 MB; priority-axi reads at most this much. */
14
+ export const MAX_ANSWER_BYTES = 32 * 2 ** 20;
10
15
  const MAX_RETRY_AFTER_S = 15;
11
16
  export const defaultDeps = {
12
17
  fetch: (...args) => fetch(...args),
@@ -22,12 +27,113 @@ function headers(settings, withBody) {
22
27
  ...(withBody ? { 'Content-Type': 'application/json' } : {}),
23
28
  };
24
29
  }
30
+ /** Milliseconds left before COMIS_DEADLINE, less a one-second margin. */
31
+ export function timeLeft(settings, deps) {
32
+ return settings.deadline === undefined
33
+ ? Number.POSITIVE_INFINITY
34
+ : settings.deadline - (deps.now ?? Date.now)() - 1000;
35
+ }
36
+ const WORKER = 'Run it from a worker, which has more time: the first index build and a cold find catalog each take about 30 s.';
37
+ // Errors that prove nothing was sent: no address, no connection, a refused
38
+ // TLS handshake or a refused proxy tunnel. Anything else may come after the
39
+ // request went out.
40
+ const BEFORE_SENDING = new Set([
41
+ 'ECONNREFUSED',
42
+ 'ENOTFOUND',
43
+ 'EAI_AGAIN',
44
+ 'UND_ERR_CONNECT_TIMEOUT',
45
+ 'DEPTH_ZERO_SELF_SIGNED_CERT',
46
+ 'SELF_SIGNED_CERT_IN_CHAIN',
47
+ 'ERR_TLS_HANDSHAKE_TIMEOUT',
48
+ 'ERR_SSL_WRONG_VERSION_NUMBER',
49
+ ]);
50
+ const TLS_HANDSHAKE = /^(CERT_|UNABLE_TO_|ERR_TLS_CERT_|ERR_SSL_TLSV1_ALERT_|ERR_SSL_SSLV3_ALERT_HANDSHAKE)/;
51
+ const PROXY_REFUSED = /Proxy response \(\d+\) !== 200 when HTTP Tunneling/;
52
+ /** True only when the error proves the request never left this machine. */
53
+ export function beforeSending(error) {
54
+ const codes = [];
55
+ let proxyRefused = false;
56
+ const walk = (e, depth) => {
57
+ if (!e || typeof e !== 'object' || depth > 6)
58
+ return;
59
+ const { code, message, cause, errors } = e;
60
+ if (typeof code === 'string')
61
+ codes.push(code);
62
+ if (typeof message === 'string' && PROXY_REFUSED.test(message))
63
+ proxyRefused = true;
64
+ if (Array.isArray(errors))
65
+ for (const x of errors)
66
+ walk(x, depth + 1);
67
+ walk(cause, depth + 1);
68
+ };
69
+ walk(error, 0);
70
+ if (proxyRefused)
71
+ return true;
72
+ return (codes.length > 0 &&
73
+ codes.every((c) => BEFORE_SENDING.has(c) || TLS_HANDSHAKE.test(c)));
74
+ }
75
+ /** What a write did, in words, for its error messages. */
76
+ function writeName(call) {
77
+ if (call.method === 'PATCH')
78
+ return 'update';
79
+ return call.path.includes('(') ? 'new line' : 'create';
80
+ }
81
+ const CHECK_FIRST = 'Check with `priority-axi show` or `priority-axi get` before sending it again. Do not retry.';
82
+ /** The sentence for a write whose outcome is unknown once it was sent. */
83
+ export function maySaved(call, what) {
84
+ return `${what}, so Priority may have saved the ${writeName(call)}. ${CHECK_FIRST}`;
85
+ }
86
+ /** Read the body, at most MAX_ANSWER_BYTES. */
87
+ async function readBody(response) {
88
+ if (!response.body)
89
+ return Buffer.alloc(0);
90
+ const reader = response.body.getReader();
91
+ const chunks = [];
92
+ let total = 0;
93
+ for (;;) {
94
+ const { done, value } = await reader.read();
95
+ if (done)
96
+ break;
97
+ total += value.byteLength;
98
+ if (total > MAX_ANSWER_BYTES) {
99
+ await reader.cancel().catch(() => { });
100
+ throw new TooLarge(total);
101
+ }
102
+ chunks.push(value);
103
+ }
104
+ return Buffer.concat(chunks, total);
105
+ }
106
+ class TooLarge extends Error {
107
+ bytes;
108
+ constructor(bytes) {
109
+ super('too large');
110
+ this.bytes = bytes;
111
+ }
112
+ }
25
113
  async function once(settings, call, deps) {
26
114
  if (call.method !== 'GET' && call.path.includes('%')) {
27
115
  throw new AxiError('internal_error', 'A write path must not be percent-encoded.');
28
116
  }
117
+ const write = call.method !== 'GET';
118
+ const left = timeLeft(settings, deps);
119
+ if (write && left + 1000 < WRITE_MIN_MS) {
120
+ throw new AxiError('unreachable', `Only ${Math.max(0, Math.floor((left + 1000) / 1000))} s are left before this command's deadline (COMIS_DEADLINE): not enough time for the owner's approval hold, so nothing was sent. Run it in a worker, which has more time.`);
121
+ }
122
+ if (!write && left <= 0) {
123
+ throw new AxiError('unreachable', `The time for this command ran out before Priority was asked. ${WORKER}`);
124
+ }
125
+ const base = write
126
+ ? (deps.timeouts?.write ?? WRITE_TIMEOUT_MS)
127
+ : (deps.timeouts?.read ?? READ_TIMEOUT_MS);
128
+ const timeout = Math.min(base, left);
129
+ const capped = left < base;
130
+ const seconds = Math.max(1, Math.round(timeout / 1000));
131
+ const timedOutText = () => write
132
+ ? maySaved(call, `Priority did not answer within ${seconds} s after the ${writeName(call)} was sent`)
133
+ : capped
134
+ ? `Priority did not answer within the ${seconds} s left before this command's deadline. ${WORKER}`
135
+ : `Priority did not answer within ${seconds} s. Filter large document screens, or read fewer records.`;
29
136
  const url = `${serviceRoot(settings)}/${call.path}${call.query ?? ''}`;
30
- const timeout = call.method === 'GET' ? READ_TIMEOUT_MS : WRITE_TIMEOUT_MS;
31
137
  const started = performance.now();
32
138
  let response;
33
139
  try {
@@ -41,19 +147,31 @@ async function once(settings, call, deps) {
41
147
  }
42
148
  catch (error) {
43
149
  const timedOut = error instanceof Error && error.name === 'TimeoutError';
44
- throw new AxiError('unreachable', timedOut
45
- ? `Priority did not answer within ${timeout / 1000} s.`
46
- : 'Priority could not be reached. Check the address, or whether the Gate is running.');
150
+ if (timedOut)
151
+ throw new AxiError('unreachable', timedOutText());
152
+ if (beforeSending(error)) {
153
+ throw new AxiError('unreachable', `Priority could not be reached${write ? ', so nothing was sent' : ''}. Check the address, or whether the Gate is running.`);
154
+ }
155
+ throw new AxiError('unreachable', write
156
+ ? maySaved(call, `The connection to Priority broke after the ${writeName(call)} was sent`)
157
+ : 'The connection to Priority broke before it answered. Try again; if it fails again, check the address or whether the Gate is running.');
47
158
  }
48
159
  let buffer;
49
160
  try {
50
- buffer = Buffer.from(await response.arrayBuffer());
161
+ buffer = await readBody(response);
51
162
  }
52
- catch {
163
+ catch (error) {
164
+ if (error instanceof TooLarge) {
165
+ throw new AxiError('output_too_large', write
166
+ ? maySaved(call, `Priority's answer is over ${MAX_ANSWER_BYTES / 2 ** 20} MB, more than priority-axi reads`)
167
+ : `Priority's answer is over ${MAX_ANSWER_BYTES / 2 ** 20} MB, more than priority-axi reads. Read less with --where, --fields, fewer --with sub-screens or a smaller --limit.`, { limit: MAX_ANSWER_BYTES });
168
+ }
169
+ if (error instanceof Error && error.name === 'TimeoutError')
170
+ throw new AxiError('unreachable', timedOutText());
53
171
  // Priority 23.1 can drop the connection part way through an answer.
54
- throw new AxiError('unreachable', call.method === 'GET'
55
- ? 'Priority broke off its answer part way through. Try again with a smaller --limit or fewer --with sub-screens.'
56
- : 'Priority broke off its answer to the create, so it may have been saved. Check with priority-axi get or show before creating it again.');
172
+ throw new AxiError('unreachable', write
173
+ ? maySaved(call, `Priority broke off its answer to the ${writeName(call)}`)
174
+ : 'Priority broke off its answer part way through. Try again with a smaller --limit or fewer --with sub-screens.');
57
175
  }
58
176
  const text = buffer.toString('utf8');
59
177
  let json;
@@ -80,7 +198,10 @@ export async function send(settings, call, deps = defaultDeps) {
80
198
  let answer = await once(settings, call, deps);
81
199
  if (answer.status === 429 && call.method === 'GET') {
82
200
  const wait = Number(answer.headers.get('retry-after') ?? '');
83
- if (Number.isFinite(wait) && wait >= 0 && wait <= MAX_RETRY_AFTER_S) {
201
+ if (Number.isFinite(wait) &&
202
+ wait >= 0 &&
203
+ wait <= MAX_RETRY_AFTER_S &&
204
+ wait * 1000 < timeLeft(settings, deps)) {
84
205
  await deps.sleep(wait * 1000);
85
206
  answer = await once(settings, call, deps);
86
207
  }
@@ -90,8 +211,16 @@ export async function send(settings, call, deps = defaultDeps) {
90
211
  }
91
212
  const error = classify(answer, {
92
213
  company: settings.company,
214
+ method: call.method,
93
215
  ...call.context,
94
216
  });
217
+ if (error && call.method !== 'GET' && error.code === 'priority_error') {
218
+ // A server or proxy failure after the write went out: it may have landed.
219
+ const said = /[.!?]$/.test(error.message)
220
+ ? error.message
221
+ : `${error.message}.`;
222
+ throw new AxiError(error.code, `${said} Priority may have saved the ${writeName(call)} anyway. ${CHECK_FIRST}`, error.fields);
223
+ }
95
224
  if (error)
96
225
  throw error;
97
226
  return answer;
@@ -2,7 +2,7 @@
2
2
  // renamed, so a crash leaves the old file or the new one, never half of each.
3
3
  // A file that cannot be read is treated as missing and rebuilt.
4
4
  import { createHash, randomBytes } from 'node:crypto';
5
- import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
5
+ import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
6
6
  import { homedir } from 'node:os';
7
7
  import { dirname, join } from 'node:path';
8
8
  import { buildIndex, INDEX_FORMAT } from './build.js';
@@ -35,6 +35,79 @@ export function writeJsonAtomic(path, value) {
35
35
  throw error;
36
36
  }
37
37
  }
38
+ // ---------- an advisory lock around slow builds ----------
39
+ /** A lock older than this is from a run that died; it is taken over. */
40
+ export const LOCK_STALE_MS = 5 * 60 * 1000;
41
+ /** How long to wait for another run's build before building anyway. */
42
+ export const LOCK_WAIT_MS = 90_000;
43
+ const LOCK_POLL_MS = 250;
44
+ function alive(pid) {
45
+ try {
46
+ process.kill(pid, 0);
47
+ return true;
48
+ }
49
+ catch (error) {
50
+ return error.code === 'EPERM';
51
+ }
52
+ }
53
+ function stale(path, now) {
54
+ try {
55
+ const pid = Number(readFileSync(path, 'utf8').split(' ')[0]);
56
+ if (Number.isSafeInteger(pid) && pid > 0 && !alive(pid))
57
+ return true;
58
+ return now - statSync(path).mtimeMs > LOCK_STALE_MS;
59
+ }
60
+ catch {
61
+ return false;
62
+ }
63
+ }
64
+ /**
65
+ * Run a build while holding an advisory lock file, so that concurrent cold
66
+ * runs on one cache wait for one download instead of each pulling the same
67
+ * metadata or catalog. `ready` is checked after waiting: when another run
68
+ * built it meanwhile, its result is used. The lock is only a courtesy: when it
69
+ * cannot be taken within `waitMs`, or the cache cannot be written, the build
70
+ * runs anyway.
71
+ */
72
+ export async function withBuildLock(path, ready, build, waitMs = LOCK_WAIT_MS) {
73
+ const until = Date.now() + Math.max(0, waitMs);
74
+ let held = false;
75
+ let waited = false;
76
+ for (;;) {
77
+ try {
78
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
79
+ const fd = openSync(path, 'wx', 0o600);
80
+ writeFileSync(fd, `${process.pid} ${new Date().toISOString()}`);
81
+ closeSync(fd);
82
+ held = true;
83
+ break;
84
+ }
85
+ catch (error) {
86
+ if (error.code !== 'EEXIST')
87
+ break;
88
+ if (stale(path, Date.now())) {
89
+ rmSync(path, { force: true });
90
+ continue;
91
+ }
92
+ if (Date.now() >= until)
93
+ break;
94
+ waited = true;
95
+ await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
96
+ }
97
+ }
98
+ try {
99
+ if (waited || held) {
100
+ const done = ready();
101
+ if (done !== undefined)
102
+ return done;
103
+ }
104
+ return await build();
105
+ }
106
+ finally {
107
+ if (held)
108
+ rmSync(path, { force: true });
109
+ }
110
+ }
38
111
  function isIndex(value) {
39
112
  if (!value || typeof value !== 'object')
40
113
  return false;
@@ -74,11 +147,25 @@ export async function loadIndex(dir, source, opts) {
74
147
  const reason = staleReason(cached, opts);
75
148
  if (cached && !reason)
76
149
  return { index: cached };
77
- const version = opts.liveVersion ?? (await source.fetchVersion());
78
- const { csdl, bytes, ms } = await source.fetchMetadata();
79
- const index = buildIndex(csdl, { version, builtAt: opts.now.toISOString() });
80
- writeJsonAtomic(join(dir, 'index.json'), index);
81
- return { index, rebuilt: { reason: reason ?? 'missing', bytes, ms } };
150
+ return withBuildLock(join(dir, 'index.lock'), () => {
151
+ // Another run built it while this one waited. A refresh still rebuilds.
152
+ const built = readIndex(dir);
153
+ if (!built ||
154
+ opts.refresh ||
155
+ built.builtAt === cached?.builtAt ||
156
+ staleReason(built, { ...opts, refresh: false }))
157
+ return undefined;
158
+ return { index: built };
159
+ }, async () => {
160
+ const version = opts.liveVersion ?? (await source.fetchVersion());
161
+ const { csdl, bytes, ms } = await source.fetchMetadata();
162
+ const index = buildIndex(csdl, {
163
+ version,
164
+ builtAt: opts.now.toISOString(),
165
+ });
166
+ writeJsonAtomic(join(dir, 'index.json'), index);
167
+ return { index, rebuilt: { reason: reason ?? 'missing', bytes, ms } };
168
+ }, opts.lockWaitMs);
82
169
  }
83
170
  export function readReach(dir) {
84
171
  const value = readJson(join(dir, 'reach.json'));
@@ -124,7 +124,7 @@ export function layout(screen, sub) {
124
124
  parentKey: top.key,
125
125
  };
126
126
  }
127
- function catalogPath(dir, screen, sub) {
127
+ export function catalogPath(dir, screen, sub) {
128
128
  return join(dir, 'find', `${screen}${sub ? `.${sub}` : ''}.json`);
129
129
  }
130
130
  export function readCatalog(dir, screen, sub, columns, now) {