@lowdefy/server-dev 6.1.0 → 7.1.0

package/manager/utils/createIdleGc.test.mjs

@@ -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 { jest } from '@jest/globals';
+
+import createIdleGc from './createIdleGc.mjs';
+
+beforeEach(() => {
+  // performance is not redefinable on this Node, and nothing here reads it.
+  jest.useFakeTimers({ doNotFake: ['performance'] });
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+test('createIdleGc collects once 5 s after the last build ends', () => {
+  const gc = jest.fn();
+  const idleGc = createIdleGc({ gc });
+
+  idleGc.onBuildingChange(true);
+  idleGc.onBuildingChange(false);
+  jest.advanceTimersByTime(4999);
+  expect(gc).not.toHaveBeenCalled();
+  jest.advanceTimersByTime(1);
+
+  expect(gc).toHaveBeenCalledTimes(1);
+  jest.advanceTimersByTime(60_000);
+  expect(gc).toHaveBeenCalledTimes(1);
+});
+
+test('createIdleGc cancels the collection when a build starts within 5 s', () => {
+  const gc = jest.fn();
+  const idleGc = createIdleGc({ gc });
+
+  idleGc.onBuildingChange(false);
+  jest.advanceTimersByTime(3000);
+  idleGc.onBuildingChange(true);
+  jest.advanceTimersByTime(60_000);
+
+  expect(gc).not.toHaveBeenCalled();
+});
+
+test('createIdleGc collects once after several back-to-back builds', () => {
+  const gc = jest.fn();
+  const idleGc = createIdleGc({ gc });
+
+  for (let i = 0; i < 4; i += 1) {
+    idleGc.onBuildingChange(true);
+    jest.advanceTimersByTime(1000);
+    idleGc.onBuildingChange(false);
+    jest.advanceTimersByTime(1000);
+  }
+  jest.advanceTimersByTime(5000);
+
+  expect(gc).toHaveBeenCalledTimes(1);
+});
+
+test('createIdleGc exposes a working gc in a process started without --expose-gc', () => {
+  jest.useRealTimers();
+  const idleGc = createIdleGc({ delayMs: 0 });
+
+  expect(() => idleGc.onBuildingChange(true)).not.toThrow();
+});

package/manager/utils/createRequestActivity.mjs

@@ -0,0 +1,100 @@
+/*
+  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.
+*/
+
+/*
+Whether anyone is using this dev server, for readers in other processes: the
+hub stops a server nobody has used for a while, judged from the fields this
+writes into the instance record (lastActivityAt, activeRequests). The manager
+counts here because it owns the public port and outlives every child restart,
+so it sees every caller (agents, lowdefy test, curl, the browser) and keeps
+its count across restarts.
+
+A page load is hundreds of short requests, so writes are throttled to one
+per throttleMs, with a trailing write so the final count always lands. The
+record is then never more than throttleMs behind, far inside the shortest
+idle limit. A request starting while the record last said 0 in flight is
+written at once, so a reader never sees a busy server as idle-with-nothing-
+in-flight longer than it takes to write.
+*/
+function createRequestActivity({ onChange, throttleMs = 5000, now = Date.now }) {
+  let activeRequests = 0;
+  let lastActivityAt = now();
+  let lastWriteAt = -Infinity;
+  let writtenActiveRequests = 0;
+  let trailingTimer = null;
+
+  function write() {
+    if (trailingTimer !== null) {
+      clearTimeout(trailingTimer);
+      trailingTimer = null;
+    }
+    lastWriteAt = now();
+    writtenActiveRequests = activeRequests;
+    onChange({ lastActivityAt: new Date(lastActivityAt).toISOString(), activeRequests });
+  }
+
+  function schedule() {
+    const sinceWrite = now() - lastWriteAt;
+    if (sinceWrite >= throttleMs) {
+      write();
+      return;
+    }
+    if (trailingTimer === null) {
+      trailingTimer = setTimeout(write, throttleMs - sinceWrite);
+      // A pending write must not keep the manager alive on shutdown.
+      trailingTimer.unref?.();
+    }
+  }
+
+  function touch() {
+    lastActivityAt = now();
+    schedule();
+  }
+
+  function begin() {
+    activeRequests += 1;
+    lastActivityAt = now();
+    if (writtenActiveRequests === 0) {
+      write();
+      return;
+    }
+    schedule();
+  }
+
+  function end() {
+    activeRequests -= 1;
+    touch();
+  }
+
+  // Counts one request from now until its response finishes or its client goes away.
+  function trackResponse(res) {
+    begin();
+    let ended = false;
+    function onEnd() {
+      if (ended) return;
+      ended = true;
+      end();
+    }
+    res.once('finish', onEnd);
+    res.once('close', onEnd);
+  }
+
+  write();
+
+  return { begin, end, touch, trackResponse };
+}
+
+export default createRequestActivity;

package/manager/utils/createRequestActivity.test.mjs

@@ -0,0 +1,121 @@
+/*
+  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 { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+import createRequestActivity from './createRequestActivity.mjs';
+
+beforeEach(() => {
+  jest.useFakeTimers({ now: new Date('2026-10-02T10:00:00.000Z'), doNotFake: ['performance'] });
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+test('createRequestActivity writes the starting activity at once', () => {
+  const onChange = jest.fn();
+  createRequestActivity({ onChange });
+  expect(onChange.mock.calls).toEqual([
+    [{ lastActivityAt: '2026-10-02T10:00:00.000Z', activeRequests: 0 }],
+  ]);
+});
+
+test('createRequestActivity counts requests in and out of flight', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  jest.advanceTimersByTime(10000);
+  activity.begin();
+  activity.begin();
+  activity.end();
+  jest.advanceTimersByTime(5000);
+  expect(onChange.mock.calls.at(-1)[0].activeRequests).toBe(1);
+  activity.end();
+  jest.advanceTimersByTime(5000);
+  expect(onChange.mock.calls.at(-1)[0]).toEqual({
+    lastActivityAt: '2026-10-02T10:00:15.000Z',
+    activeRequests: 0,
+  });
+});
+
+test('createRequestActivity writes a request starting on an idle record at once', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  jest.advanceTimersByTime(1000);
+  activity.begin();
+  expect(onChange).toHaveBeenCalledTimes(2);
+  expect(onChange.mock.calls[1][0]).toEqual({
+    lastActivityAt: '2026-10-02T10:00:01.000Z',
+    activeRequests: 1,
+  });
+});
+
+test('createRequestActivity writes the end of the last request at once when the record is older than the throttle', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  activity.begin();
+  jest.advanceTimersByTime(60000);
+  activity.end();
+  expect(onChange.mock.calls.at(-1)[0]).toEqual({
+    lastActivityAt: '2026-10-02T10:01:00.000Z',
+    activeRequests: 0,
+  });
+});
+
+test('createRequestActivity bounds the writes for a burst of short requests and lands the final value', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  onChange.mockClear();
+  for (let i = 0; i < 100; i += 1) {
+    activity.begin();
+    jest.advanceTimersByTime(20);
+    activity.end();
+    jest.advanceTimersByTime(20);
+  }
+  jest.advanceTimersByTime(5000);
+  expect(onChange.mock.calls.length).toBeLessThanOrEqual(3);
+  expect(onChange.mock.calls.at(-1)[0]).toEqual({
+    lastActivityAt: new Date(Date.parse('2026-10-02T10:00:00.000Z') + 3980).toISOString(),
+    activeRequests: 0,
+  });
+});
+
+test('createRequestActivity touch refreshes lastActivityAt through the throttle', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  jest.advanceTimersByTime(2000);
+  activity.touch();
+  expect(onChange).toHaveBeenCalledTimes(1);
+  jest.advanceTimersByTime(3000);
+  expect(onChange).toHaveBeenCalledTimes(2);
+  expect(onChange.mock.calls[1][0].lastActivityAt).toBe('2026-10-02T10:00:02.000Z');
+});
+
+test('createRequestActivity trackResponse ends a request once, on finish or close', () => {
+  const onChange = jest.fn();
+  const activity = createRequestActivity({ onChange });
+  const res = new EventEmitter();
+  activity.trackResponse(res);
+  expect(onChange.mock.calls.at(-1)[0].activeRequests).toBe(1);
+  res.emit('finish');
+  res.emit('close');
+  jest.advanceTimersByTime(5000);
+  expect(onChange.mock.calls.at(-1)[0].activeRequests).toBe(0);
+  activity.begin();
+  expect(onChange.mock.calls.at(-1)[0].activeRequests).toBe(1);
+});

package/manager/utils/createServerArtifactTracker.mjs

@@ -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 crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { type } from '@lowdefy/helpers';
+
+// The files the dev server reads when it starts. Node never drops a loaded
+// ES module, so a change to one needs a new server process. Client-side
+// artifacts (blocks.js, operators/client.js, globals.css, ...) are served by
+// Vite, which hot-replaces them without a restart. package.json lists the
+// plugin packages: a change there needs an install first.
+const trackedFiles = [
+  'build/app.json',
+  'build/auth.json',
+  'build/config.json',
+  'build/plugins/auth/adapters.js',
+  'build/plugins/auth/providers.js',
+  'build/plugins/connections.js',
+  'build/plugins/operators/server.js',
+  'package.json',
+];
+
+function hashFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  let content = fs.readFileSync(filePath, 'utf8');
+  // Build keys (~k) change with unrelated edits and mean nothing to the server.
+  if (filePath.endsWith('.json')) {
+    content = JSON.stringify(
+      JSON.parse(content, (_, value) => {
+        if (!type.isObject(value)) return value;
+        delete value['~k'];
+        return value;
+      })
+    );
+  }
+  return crypto.createHash('sha1').update(content).digest('base64');
+}
+
+// Compares these files with what the running server started with, so a
+// build restarts the server only when it changed something the server read.
+function createServerArtifactTracker({ directories }) {
+  function hashAll() {
+    return Object.fromEntries(
+      trackedFiles.map((file) => [file, hashFile(path.join(directories.server, file))])
+    );
+  }
+
+  let started = hashAll();
+
+  function record() {
+    started = hashAll();
+  }
+
+  function check() {
+    const current = hashAll();
+    const changed = trackedFiles.filter((file) => current[file] !== started[file]);
+    return {
+      install: changed.includes('package.json'),
+      restart: changed.length > 0,
+    };
+  }
+
+  return { check, record };
+}
+
+export default createServerArtifactTracker;

package/manager/utils/createServerArtifactTracker.test.mjs

@@ -0,0 +1,78 @@
+/*
+  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 createServerArtifactTracker from './createServerArtifactTracker.mjs';
+
+let server;
+
+function write(file, content) {
+  fs.mkdirSync(path.dirname(path.join(server, file)), { recursive: true });
+  fs.writeFileSync(path.join(server, file), content);
+}
+
+beforeEach(() => {
+  server = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-server-artifacts-'));
+  write('package.json', '{"dependencies":{}}');
+  write('build/config.json', '{"~k":"a","theme":{}}');
+  write('build/plugins/connections.js', 'export default {};');
+});
+
+afterEach(() => {
+  fs.rmSync(server, { recursive: true, force: true });
+});
+
+test.each([
+  ['nothing changed', () => {}, { install: false, restart: false }],
+  [
+    'only build keys changed',
+    () => write('build/config.json', '{"~k":"b","theme":{}}'),
+    { install: false, restart: false },
+  ],
+  [
+    'a new connection type',
+    () => write('build/plugins/connections.js', 'export { A };'),
+    { install: false, restart: true },
+  ],
+  [
+    'a server artifact appeared',
+    () => write('build/auth.json', '{}'),
+    { install: false, restart: true },
+  ],
+  [
+    'a new plugin package',
+    () => write('package.json', '{"dependencies":{"a":"1"}}'),
+    { install: true, restart: true },
+  ],
+])('the server artifact tracker reports %s', (_, change, expected) => {
+  const tracker = createServerArtifactTracker({ directories: { server } });
+  tracker.record();
+  change();
+
+  expect(tracker.check()).toEqual(expected);
+});
+
+test('the server artifact tracker compares with what the server last started with', () => {
+  const tracker = createServerArtifactTracker({ directories: { server } });
+  write('build/plugins/connections.js', 'export { A };');
+  expect(tracker.check().restart).toBe(true);
+
+  tracker.record();
+  expect(tracker.check().restart).toBe(false);
+});

package/manager/utils/createServerEnv.mjs

@@ -0,0 +1,39 @@
+/*
+  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 resolveDevAuthUrl from './resolveDevAuthUrl.mjs';
+
+// The environment of the Vite child, shared with the dependency optimiser so
+// it resolves the same Vite config (and so the same cache hash) as the child
+// that later reads its cache. Read on every call: a .env edit can change
+// BETTER_AUTH_URL, and the watcher restarts the child with the reloaded value.
+function createServerEnv(context) {
+  return {
+    ...process.env,
+    LOWDEFY_DIRECTORY_CONFIG: context.directories.config,
+    // Set only while the manager's mail sink listens: the child cannot
+    // tell from LOWDEFY_DEV_SMTP_PORT alone, which a later .env edit can
+    // add without a sink (it starts once, with the manager).
+    LOWDEFY_SERVER_DEV_MAIL_SINK: context.mailSink ? 'true' : undefined,
+    PORT: context.internalPort,
+    BETTER_AUTH_URL: resolveDevAuthUrl({
+      configured: process.env.BETTER_AUTH_URL,
+      port: context.options.port,
+    }).authUrl,
+  };
+}
+
+export default createServerEnv;

package/manager/utils/filesHaveSameBytes.mjs

@@ -0,0 +1,41 @@
+/*
+  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/promises';
+
+async function statIfExists(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// Sizes are compared first, so a changed file of a new length costs two stats
+// and no reads.
+async function filesHaveSameBytes({ a, b }) {
+  const [statsA, statsB] = await Promise.all([statIfExists(a), statIfExists(b)]);
+  if (statsA === null || statsB === null || statsA.size !== statsB.size) {
+    return false;
+  }
+  const [bytesA, bytesB] = await Promise.all([fs.readFile(a), fs.readFile(b)]);
+  return bytesA.equals(bytesB);
+}
+
+export default filesHaveSameBytes;

package/manager/utils/findBuildFilesOutsideWatch.mjs

@@ -0,0 +1,59 @@
+/*
+  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 path from 'path';
+import { type } from '@lowdefy/helpers';
+
+function isInside({ directory, filePath }) {
+  return filePath === directory || filePath.startsWith(`${directory}${path.sep}`);
+}
+
+// refMap.json holds the config build's refs; a jitMaps/ file holds the refs a
+// JIT page build added, under refMap. A jitMaps file can be pruned before its
+// change is handled, and then has nothing to add.
+function readRefMap(mapsFile) {
+  if (path.basename(mapsFile) === 'refMap.json') {
+    return JSON.parse(fs.readFileSync(mapsFile, 'utf8'));
+  }
+  try {
+    return JSON.parse(fs.readFileSync(mapsFile, 'utf8')).refMap ?? {};
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+}
+
+// Every file a build reads is recorded in a ref map: app refs by their path
+// relative to the config directory, module refs by absolute path. Returns the
+// files the given maps files record that lie outside every watched directory,
+// such as a file a local module refs with ../ from beside the module.
+function findBuildFilesOutsideWatch({ mapsFiles, configDirectory, watchRoots }) {
+  const files = new Set();
+  for (const mapsFile of mapsFiles) {
+    for (const entry of Object.values(readRefMap(mapsFile))) {
+      if (!type.isString(entry.path)) continue;
+      const filePath = path.resolve(configDirectory, entry.path);
+      if (watchRoots.some((directory) => isInside({ directory, filePath }))) continue;
+      files.add(filePath);
+    }
+  }
+  return [...files];
+}
+
+export default findBuildFilesOutsideWatch;