@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/docs/waitForBuild.js

@@ -0,0 +1,50 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { wait } from '@lowdefy/helpers';
+import { readDevInstanceAsync } from '@lowdefy/node-utils';
+
+// An edit reaches the manager's file watcher a moment after it is saved, and
+// the watcher debounces before building, so an agent that asks for build
+// status straight after an edit would read the build before it. The manager
+// sets `building` in the instance record from the first change of a batch
+// until the batch is processed; this waits for that to clear. The grace
+// window covers an edit the watcher has not seen yet. Reads without blocking:
+// it polls inside the dev server, and on Windows a start time read starts
+// PowerShell.
+async function waitForBuild({ graceMs = 1000, timeoutMs = 60000, intervalMs = 100 } = {}) {
+  const configDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
+  const isBuilding = async () =>
+    (await readDevInstanceAsync({ configDirectory }))?.building === true;
+  const start = Date.now();
+  let sawBuild = false;
+  while (Date.now() - start < graceMs) {
+    if (await isBuilding()) {
+      sawBuild = true;
+      break;
+    }
+    await wait(intervalMs);
+  }
+  while (await isBuilding()) {
+    if (Date.now() - start > timeoutMs) {
+      return { settled: false, waitedMs: Date.now() - start };
+    }
+    await wait(intervalMs);
+  }
+  return { settled: true, sawBuild, waitedMs: Date.now() - start };
+}
+
+export default waitForBuild;

package/lib/docs/waitForBuild.test.mjs

@@ -0,0 +1,75 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import waitForBuild from './waitForBuild.js';
+
+let configDirectory;
+const originalConfigDirectory = process.env.LOWDEFY_DIRECTORY_CONFIG;
+
+function writeInstance({ building }) {
+  fs.writeFileSync(
+    path.join(configDirectory, '.lowdefy', 'instance.json'),
+    JSON.stringify({ pid: process.pid, configDirectory, state: 'ready', building })
+  );
+}
+
+beforeEach(() => {
+  // The path as the manager records it (realpathSync.native), which on Windows
+  // also expands 8.3 short names such as RUNNER~1 in the temp directory.
+  configDirectory = fs.realpathSync.native(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'wait-for-build-'))
+  );
+  fs.mkdirSync(path.join(configDirectory, '.lowdefy'));
+  process.env.LOWDEFY_DIRECTORY_CONFIG = configDirectory;
+});
+
+afterEach(() => {
+  process.env.LOWDEFY_DIRECTORY_CONFIG = originalConfigDirectory;
+  fs.rmSync(configDirectory, { recursive: true, force: true });
+});
+
+test('waitForBuild waits until the manager has processed the pending change', async () => {
+  writeInstance({ building: true });
+  setTimeout(() => writeInstance({ building: false }), 150);
+  const result = await waitForBuild({ intervalMs: 10 });
+  expect(result).toMatchObject({ settled: true, sawBuild: true });
+  expect(result.waitedMs).toBeGreaterThanOrEqual(140);
+});
+
+test('waitForBuild catches a change the watcher sees just after the call', async () => {
+  writeInstance({ building: false });
+  setTimeout(() => writeInstance({ building: true }), 50);
+  setTimeout(() => writeInstance({ building: false }), 200);
+  const result = await waitForBuild({ intervalMs: 10, graceMs: 500 });
+  expect(result).toMatchObject({ settled: true, sawBuild: true });
+  expect(result.waitedMs).toBeGreaterThanOrEqual(190);
+});
+
+test('waitForBuild returns after the grace window when nothing is pending', async () => {
+  writeInstance({ building: false });
+  const result = await waitForBuild({ intervalMs: 10, graceMs: 100 });
+  expect(result).toMatchObject({ settled: true, sawBuild: false });
+});
+
+test('waitForBuild gives up after the timeout and says so', async () => {
+  writeInstance({ building: true });
+  const result = await waitForBuild({ intervalMs: 10, graceMs: 10, timeoutMs: 100 });
+  expect(result.settled).toBe(false);
+});

package/lib/docs/waitForJourneyEmail.js

@@ -0,0 +1,77 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import JourneyStepError from './JourneyStepError.js';
+import readMailOutbox from './readMailOutbox.js';
+
+const POLL_MS = 100;
+
+function describeWanted({ to, subject }) {
+  if (type.isUndefined(subject)) {
+    return `an email to "${to}"`;
+  }
+  return `an email to "${to}" with a subject containing "${subject}"`;
+}
+
+// Mail received before the journey started belongs to an earlier run against
+// the same dev server, so it is never a candidate.
+function isCandidate({ message, since }) {
+  return Date.parse(message.receivedAt) >= since;
+}
+
+function findNewest({ messages, to, subject, since }) {
+  const address = to.toLowerCase();
+  const matches = messages.filter(
+    (message) =>
+      isCandidate({ message, since }) &&
+      message.to.some((recipient) => recipient.toLowerCase() === address) &&
+      (type.isUndefined(subject) || message.subject.includes(subject))
+  );
+  return matches[matches.length - 1];
+}
+
+// The newest email to `to` (subject containing `subject`) received since the
+// journey started, waiting up to `timeout` for one to arrive. Newest, like a
+// person opening their inbox: an email the journey caused is sent within the
+// request that caused it, so it is already here when the next step runs, and
+// reading an email twice (an invitation link clicked again after signing up)
+// reads the same one.
+async function waitForJourneyEmail({ page, params, since, configDirectory, timeout }) {
+  const { to, subject } = params;
+  const deadline = Date.now() + timeout;
+  let messages = await readMailOutbox({ configDirectory });
+  let message = findNewest({ messages, to, subject, since });
+  while (type.isUndefined(message)) {
+    if (Date.now() >= deadline) {
+      const received = messages
+        .filter((candidate) => isCandidate({ message: candidate, since }))
+        .map((candidate) => `"${candidate.subject}" to ${candidate.to.join(', ')}`);
+      const expected = describeWanted({ to, subject });
+      throw new JourneyStepError(`Timed out after ${timeout}ms waiting for ${expected}.`, {
+        expected,
+        actual: received.length > 0 ? received : 'no email received during this journey',
+      });
+    }
+    await page.waitForTimeout(POLL_MS);
+    messages = await readMailOutbox({ configDirectory });
+    message = findNewest({ messages, to, subject, since });
+  }
+  return message;
+}
+
+export default waitForJourneyEmail;

package/lib/docs/withBrowserSlot.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { acquireMachineSlot } from '@lowdefy/node-utils';
+
+import acquireBrowserSlot from './acquireBrowserSlot.js';
+
+/*
+Runs one browser operation (a journey, a screenshot, a state inspection, an
+operator evaluation, a state load) in one of the machine's browser slots, so
+at most three run at once across every dev server on the machine, however
+the call came in. A slot covers the whole operation, every page and actor of
+a journey included: a bound per page would deadlock a journey with more
+actors than slots. The operation's own timeouts start once the slot is
+taken. A wait that outlasts the slot wait (see acquireBrowserSlot) is answered as the
+operation's error, like every other failure of these tools.
+*/
+async function withBrowserSlot({ task, acquire = acquireMachineSlot }) {
+  let slot;
+  try {
+    slot = await acquireBrowserSlot({ acquire });
+  } catch (error) {
+    return { error: error.message };
+  }
+  try {
+    return await task();
+  } finally {
+    slot.release();
+  }
+}
+
+export default withBrowserSlot;

package/lib/docs/withBrowserSlot.test.mjs

@@ -0,0 +1,75 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { jest } from '@jest/globals';
+
+import withBrowserSlot from './withBrowserSlot.js';
+
+function fakeAcquire() {
+  const release = jest.fn();
+  const acquire = jest.fn(async () => ({ release }));
+  return { acquire, release };
+}
+
+test('withBrowserSlot runs the operation in a browser slot and releases it after', async () => {
+  const { acquire, release } = fakeAcquire();
+  const task = jest.fn(async () => {
+    expect(release).not.toHaveBeenCalled();
+    return { data: 'png' };
+  });
+  await expect(withBrowserSlot({ task, acquire })).resolves.toEqual({ data: 'png' });
+  expect(acquire).toHaveBeenCalledWith({ name: 'browser', limit: 3, waitMs: 300000 });
+  expect(release).toHaveBeenCalledTimes(1);
+});
+
+test('withBrowserSlot releases the slot when the operation throws', async () => {
+  const { acquire, release } = fakeAcquire();
+  const task = async () => {
+    throw new Error('Navigation timeout of 15000 ms exceeded');
+  };
+  await expect(withBrowserSlot({ task, acquire })).rejects.toThrow('Navigation timeout');
+  expect(release).toHaveBeenCalledTimes(1);
+});
+
+test('withBrowserSlot answers a slot wait that outlasts its limit as the operation error', async () => {
+  const acquire = async () => {
+    throw new Error('All 3 browser slots on this machine stayed busy for 5 minutes. Try again.');
+  };
+  const task = jest.fn();
+  await expect(withBrowserSlot({ task, acquire })).resolves.toEqual({
+    error: 'All 3 browser slots on this machine stayed busy for 5 minutes. Try again.',
+  });
+  expect(task).not.toHaveBeenCalled();
+});
+
+test('withBrowserSlot takes real machine slots and frees them', async () => {
+  const sharedHome = process.env.LOWDEFY_HOME;
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-browser-slot-'));
+  process.env.LOWDEFY_HOME = home;
+  try {
+    const slots = path.join(home, 'slots', 'browser');
+    const result = await withBrowserSlot({ task: async () => fs.readdirSync(slots) });
+    expect(result).toEqual(['0']);
+    expect(fs.readdirSync(slots)).toEqual([]);
+  } finally {
+    process.env.LOWDEFY_HOME = sharedHome;
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/lib/docs/withDataSession.js

@@ -0,0 +1,53 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import getDataStore from './dataSets/getDataStore.js';
+import openDataSession from './dataSets/openDataSession.js';
+
+// Runs `task` on a data set's own database when the call named one: a fresh
+// database on the dev server's memory store, loaded with the data set and
+// dropped once the task settles, exactly as a journey's. The task gets
+// `dataCookie` (for a headless browser context, see openPage) and
+// `dataSession` (for a context the dev server builds itself, see
+// createLowdefyContext); both are undefined without a data set. A data set
+// that fails to load comes back as { error } without running the task.
+async function withDataSession({ dataSet, task }) {
+  if (type.isUndefined(dataSet)) {
+    return task({});
+  }
+  try {
+    await getDataStore();
+  } catch (error) {
+    return {
+      error: `Could not start the data store for data set "${dataSet.name}": ${error.message}`,
+    };
+  }
+  let session;
+  try {
+    session = await openDataSession({ dataSet });
+  } catch (error) {
+    return { error: error.message };
+  }
+  try {
+    return await task({ dataCookie: session.cookie, dataSession: session.session });
+  } finally {
+    await session.close();
+  }
+}
+
+export default withDataSession;

package/lib/server/applyDataSetRedirect.js

@@ -0,0 +1,83 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { mergeObjects, type } from '@lowdefy/helpers';
+
+import createDataSetRefusal from './createDataSetRefusal.js';
+
+// Module connections are written under their module's folder (connections/<module>/<id>.json), so
+// the pattern matches every depth.
+const connectionPathPattern = /^connections\/.+\.json$/;
+
+// A top-level key starting with _ is an operator over the whole properties object, so what it
+// evaluates to cannot be checked before it runs.
+function hasLiteralKeys(properties) {
+  return type.isObject(properties) && !Object.keys(properties).some((key) => key.startsWith('_'));
+}
+
+// The one gate for connections under a data session, for this request only. It fails closed: a
+// connection is either verifiably pointed at the session's database or the read throws. A type
+// declares how it behaves through meta.dataSet on its plugin, in one of three modes:
+// - 'redirect' takes its database from databaseUri and databaseName, so the session's are merged
+//   over its properties whether or not the data set lists it.
+// - 'walled' holds no database address and reaches MongoDB only through the walled client (the
+//   resolver's walled(connectionId) argument), so it passes unchanged: the walled connections it
+//   names are read through this same gate and take the session database as redirect connections.
+// - 'external' reaches an outside service and keeps its target.
+// Anything else, including no declaration, refuses. The gate cannot verify a walled or external
+// declaration, since properties are evaluated later and may read secrets: it is the plugin
+// author's promise. Returns a new artifact and never mutates the one it read, so it stays correct if
+// reads are ever cached.
+function applyDataSetRedirect({ context, session, connections }) {
+  const readConfigFile = context.readConfigFile;
+  context.readConfigFile = async function readConfigFileForDataSet(filePath) {
+    const artifact = await readConfigFile(filePath);
+    if (!connectionPathPattern.test(filePath) || type.isNone(artifact)) {
+      return artifact;
+    }
+    // Work that outlived its session's drain fails loudly rather than reach any database.
+    if (session.state === 'closed') {
+      throw new Error(`Data session ${session.id} has ended.`);
+    }
+    const mode = connections[artifact.type]?.meta?.dataSet;
+    if (mode === 'external' || mode === 'walled') {
+      return artifact;
+    }
+    if (mode !== 'redirect') {
+      throw createDataSetRefusal({
+        artifact,
+        session,
+        reason: 'its type does not say how to redirect it',
+      });
+    }
+    if (!hasLiteralKeys(artifact.properties)) {
+      throw createDataSetRefusal({
+        artifact,
+        session,
+        reason: 'its properties are an operator, so the redirect cannot be checked',
+      });
+    }
+    return {
+      ...artifact,
+      properties: mergeObjects([
+        artifact.properties,
+        { databaseUri: session.databaseUri, databaseName: session.databaseName },
+      ]),
+    };
+  };
+}
+
+export default applyDataSetRedirect;