Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,10 @@ A note lives in the `DESIGN.md` of the directory that owns the code it describes
- [Local messages name the product through `PRODUCT_NAME` (`utility/packageUtils.js`)](utility/DESIGN.md#local-messages-name-the-product-through-product_name-utilitypackageutilsjs) — Local lifecycle messages use the running package.json `productName`; distributions such as Harper Pro set that field instead of rewriting core sources.
- [Local times are unique across threads (`utility/lmdb/commonUtility.ts` `getNextMonotonicTime`)](utility/DESIGN.md#local-times-are-unique-across-threads-utilitylmdbcommonutilityts-getnextmonotonictime) — One `SharedArrayBuffer` clock word per process, advanced by CAS; same-node equal versions read as re-deliveries, so a shared time would drop a write. · [RocksDB arena size and flush policy stay rocksdb-js's unless configured (`utility/rocksMemoryConfig.ts`)](utility/DESIGN.md#rocksdb-arena-size-and-flush-policy-stay-rocksdb-jss-unless-configured-utilityrocksmemoryconfigts) — `storage.rocks.arenaBlockSize` and `storage.rocks.writeBufferManagerFlushPolicy` forward only a well-typed operator value; unset means rocksdb-js decides, and an explicit policy lasts until a full restart.

## integrationTests/

- [A fixture must not install from the npm registry](integrationTests/DESIGN.md#a-fixture-must-not-install-from-the-npm-registry) — Vendor production dependencies or neutralize the install.

## build-tools/ — packaging, published artifacts and local lint rules

- [Release dependencies are bundled without host binaries (`bundleDependencies.ts`)](build-tools/DESIGN.md#release-dependencies-are-bundled-without-host-binaries-bundledependenciests) — The locked JavaScript closure ships as bytes; native roots install per platform and the actual archive and consumer layout are checked.
Expand Down
36 changes: 36 additions & 0 deletions integrationTests/DESIGN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# integrationTests/ — Design notes

The end-to-end suite: fixtures, deployed components, and the harness that starts real Harper
instances.

**Read this when:** adding or regenerating a fixture under `integrationTests/`.

Index of every design note: [DESIGN.md](../DESIGN.md).

---

## A fixture must not install from the npm registry

`deploy_component` runs a real `npm install` for a package that declares production dependencies and
ships no `node_modules`, putting the public npm registry on a test's critical path. A stalled
registry socket outlives every deadline the test can set: Harper's own spawn bound is
`DEFAULT_COMMAND_TIMEOUT_MS = 60 * 60 * 1000` (`components/Application.ts`), so the client gives up
first ([harper#2752](https://github.com/HarperFast/harper/pull/2752): a stalled install surfaced as
`UND_ERR_HEADERS_TIMEOUT`).

A fixture therefore declares no production dependencies, resolves them from local files the archive
carries (`deploy/redeploy-runtime-equivalence.test.ts` builds a `file:vendor/...` dependency, which
exercises the automatic install path without a registry), neutralizes the install with
`install_command` (`components/early-hints.test.ts`), or vendors its dependencies into the archive so
`installApplication` takes its `node_modules`-present early return.
`template-redirector-3.0.1-vendored.tgz` is the last case: the published `template-redirector@3.0.1`
plus `node_modules/papaparse` at the version its manifest pins, which is why its name diverges from
the package it came from — regenerating it with `npm pack` alone would silently restore the flake.

Nothing enforces this across fixtures, and two suites still violate it: `mqtt/mqtt.test.ts` and
`components/acl-connect.test.ts` deploy fixtures whose manifests pin `@harperdb/acl-connect` and
`jsonwebtoken` with no committed `node_modules`, so a hang in either deploy is worth checking
against the instance log's `spawn:npm` line before it is diagnosed as a new bug.

For the redirector archive specifically, `components/redirector.test.ts` asserts the instance log
contains `already has node_modules; skipping install` and no `[redirector:spawn:npm]` line.
Loading
Loading