mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-09 07:10:34 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The server has about 1,100 test and helper files in `server/src/__tests__` > - `server/tsconfig.json` excludes that directory, Vitest does not check types, and no script runs the tsconfig in that directory > - So a test can call a function with the wrong arguments and still pass, and no tool reports it > - This gap hid 2,168 real type errors, and some of them hid tests that did not test what they claim > - This pull request fixes all of these errors and adds the directory to the server layers from paperclipai/paperclip#18737 > - The benefit is that a type error in a server test now fails the typecheck, with no baseline and no backlog ## Linked Issues or Issue Description Refs paperclipai/paperclip#18737, which is merged and added the server layers. Refs paperclipai/paperclip#18738, which is merged and checks the test projects outside `pnpm -r`, so it is not a duplicate. Refs paperclipai/paperclip#18137, which records that this directory has no check. **What happened?** No tool checked the types of 1,074 of the 1,101 files in `server/src/__tests__`. I searched `package.json`, the workflows, and all tsconfig files. 27 files are in the program of another tsconfig, and these 27 have 0 errors. 11 of the 27 are in `helpers/maintenance/tsconfig.json`. No script ran that project when I measured this. paperclipai/paperclip#18738 now runs it. **Expected behavior** The server typecheck checks these files, and a type error fails the check. **Steps to reproduce** 1. On the base commit, run `tsc -p server/src/__tests__/tsconfig.json --noEmit`. It reports 6,536 errors and needs 12.3 GiB. 2. Add a type error to any file in `server/src/__tests__`. 3. Run `pnpm --filter @paperclipai/server typecheck`. It passes. **Paperclip version or commit** I measured the error breakdown below on commit `8dfd632452`, with TypeScript 7.0.2. The branch now includes master up to paperclipai/paperclip#18865. **Deployment mode** Not applicable. This issue applies to development and CI. No production source file in the server changes. ### Error breakdown Each row adds one change to the row above. | Step | Total errors | Change | Cause | | --- | --- | --- | --- | | Config as committed | 6,536 | | | | Add `src/types/*.d.ts` | 4,447 | -2,089 | Config. The Express request types were missing. | | Set `rootDir` to the repository root | 2,436 | -2,011 | Config. | | Set `allowImportingTsExtensions` | 2,181 | -255 | Config. Vitest accepts `.ts` imports. | | Add `ES2024.Promise` to `lib` | 2,138 | -43 | Config. Node 24 has `Promise.withResolvers`. | | Set `allowJs` for `.mjs` imports | 2,148 | +10 | Config. It removes 8 `TS7016` errors and shows new real errors. | | Set `declaration` to false | 2,142 | -6 | Config. Tests emit nothing. | | Count only files in `server/src` | 2,058 | -84 | Other packages: 53 Daytona, 29 Runner test, 2 UI. | So 4,478 of the 6,536 errors (69%) came from config or scope, and 2,058 are real type errors in 314 files. The 29 Runner test errors are also real, which gives 2,087 errors. Tests that master added after this measurement had 81 more errors, so this pull request fixes 2,168 errors. This table classifies the first 2,058 errors. | Kind of real error | Errors | | --- | --- | | Wrong argument or assignment type | 1,023 | | Stale or partial fixture objects | 525 | | Property that the type does not have | 317 | | Missing narrowing of null or unknown | 101 | | Implicit any | 60 | | Missing name or module | 16 | | Other | 16 | ### What the type errors hid Most errors were stale fixtures and loose mocks. These errors hid real test problems, and this pull request fixes them: - **A test that never ran.** `instrumentation.test.ts` required `sdk-trace-base`, which is not installed. So 3 span tests were skipped. They now run and pass. - **Assertions that could not fail.** - `issue-thread-interactions-service` used a company ID as an issue ID. - `status-card-evaluation-work` compared `[]` with `[]` in a rollback check. - `slack-conversation-lifecycle` read `item.issueId`, which does not exist. - `email-channels` used a permission key that does not exist. - `heartbeat-project-env` imported `LOW_TRUST_REVIEW_PRESET`, which is not exported. The value was undefined. - **Postgres processes that did not stop.** 11 test files called `stop` on the test database helper. That method does not exist, and the helper method is `cleanup`. - **Arguments that the service ignored.** - `methodKey` is now `connectionMethodKey` in the Daytona, Unikraft, 1Password, and Railway tests. - 108 calls passed `"owner-user"` to a parameter that expects an options object. - 9 chat wizard fixtures passed `managementContext` as `source`, so they ran `existing_app` and not `manifest`. - 2 tests passed a `{ userId }` actor that the function ignores. - Inserts into `environments` passed a `companyId` column that the table does not have. - **Problems in tests that master added during this work.** - `sandbox-creation-operations` read `database.connectionString` when an external test database was set. In that mode `database` is undefined, so the fixture would stop with a TypeError. It now uses the external URL. - `idle-completed-history` set a Dot operation to `dispatched`. That is a Muse status, and the Dot type does not have it. The fixture now uses `admitted`, which is a real in-flight Dot status. ### Possible product problems, not changed These may be real problems in production code or types. I did not change them, because this pull request does not change production behavior: - `decisions-service` `service.create` does not validate the lenient `cancel_issue_tree` input. - `createConnection` ignores `input.connectionPurpose`. - The `createConnection` route schema default stores `{}` for `transportConfig`. - `prepareManagedAiRuntime` accepted the invalid value `mode: "connection"`. - `createBinding` accepts invalid `projectionClass` strings outside class 3. - `ensureManagedProjectWorkspace` forwards an untyped `repoRef` by spread. - `routineVariableSchema.label` is optional, but `RoutineVariable.label` is required. - `ToolRunContext.projectId` may be too strict. - `withdrawInteraction` reads `issue.status`, which its type omits. - `issueService.list` and `reconcileNativeFinalizations` omit fields that they return at runtime. - `createGitHubExternalObjectProvider` handles `tokenProvider: null`, but its type forbids this value. ## What Changed - Fixed the 2,168 type errors. The diff changes 322 test and helper files. - Corrected `server/src/__tests__/tsconfig.json`. Editors and the typecheck now read the same options and report the same errors. - Added three `test-tree` layers to `server/scripts/typecheck-layers.mjs`. They read the server layers as declarations, and any error fails them. A hash of the path selects the shard, so a new file does not move other files. - Added `server/scripts/typecheck-stubs/daytona-sdk.d.ts`. Server tests reach Daytona plugin source, and the root install does not have `@daytonaio/sdk`. - Changed two imports in `ui/src/lib/issue-execution-policy.ts` to use `.js` extensions, because server tests import this file. - Made `declarationsConfig` and `--declarations-only` skip the `test-tree` layers, because these layers emit nothing. Other projects read only the source layers. Added a test for this. - Updated `doc/DEVELOPING.md`. ## Verification Run these commands: ```sh pnpm --filter @paperclipai/server typecheck pnpm exec vitest run server/scripts/typecheck-layers.test.mjs ``` Results on macOS (arm64), Node 24, 16 cores. Each check ran after the merge of paperclipai/paperclip#18738 unless the row says otherwise: | Check | Commit | Result | | --- | --- | --- | | Server typecheck, `PAPERCLIP_TYPECHECK_LOW_MEMORY=1`, all 7 layers | `6e45a08573` | Exit 0, 0 errors, 62 seconds, peak 3.52 GiB | | `node scripts/typecheck-test-projects.mjs --low-memory` | `a3306bd13e` | Exit 0, 0 errors, 42 seconds, peak 3.25 GiB | | The same script with `--reuse-declarations` | `1b878aabc0` | Exit 0, 0 errors | | `typecheck-layers.test.mjs` and `live-recovery-work.test.ts` | `01db5634e4` | 90 passed. These include real compiler runs for a pass, a type error, and an invalid tsconfig. | | `tsconfig.declarations.json` after a full server typecheck | `0fb1e4fb0a` | It references only `below`, `cycle`, and `above`. No generated config names a `tsconfig.layers.json` file. | | Owned runtime test in `idle-completed-history` | `e8f2f448ac` | Passed, with the fix that master later replaced | | `idle-incoming-wake`, `plugin-idle-manager`, and the changed `chat-channels` test | `6e45a08573` | 30 passed | | Runner `native-execution.test.ts` | `eab4dcc1f4` | 114 passed | | The 19 server test files that changed since `eab4dcc1f4`, and `typecheck-layers.test.mjs` | `259737b700` | 4,275 of 4,277 passed. The 2 failures are in `chat-channels` and are in the list of 7 below. | The peak is the largest single process, from `/usr/bin/time -l`. Peaks for the server typecheck were between 3.42 GiB and 3.56 GiB across 8 runs. Peaks for the test projects were 3.25 GiB and 3.37 GiB across 2 runs. I did not measure a cgroup. **Runtime check of the fixes.** Types do not prove that a test still works. So I ran all 309 changed server test files, 11,929 tests, before the rebase onto paperclipai/paperclip#18737: | Result | Tests | Detail | | --- | --- | --- | | Passed | 11,913 | Includes the 2 tests and the 54 `dot-runner` tests that passed in a later run, as described below. | | Failed | 7 | The same 7 tests also fail on the commit before the fixes. | | Skipped | 9 | These tests have their own skip conditions: `sentry` 5, and 1 each in `bundled-plugin-registration`, `customer-success-cloud`, `onepassword-connection`, and `workspace-runtime-https-live-exercise`. | The 7 tests that fail with and without this change, on my machine: - 3 tests in `chat-channels` and `email-channels` stop with `ENOENT` on a `SKILL.md` file. The path is in the parent checkout, above the git worktree that I used, so I expect that the worktree is the cause. I did not prove this. - `workspace-instance-cleanup` compares `/private/var/...` with `/var/...`. This is a macOS symlink difference. - 2 tests in `git-reproducible-managed-checkouts` get `unknown_base_git_files` and expect `unpushed_managed_checkout`. I did not find the cause. - 1 more test in `chat-channels`, `materializes direct external-chat finals once`, gets `undefined`. I did not find the cause. CI is the check for these 7 tests. `ci / verify` passed on `eab4dcc1f4`. Failures during this work: - My fix to `agent-runtime-connector-access` changed an invalid permission key in the setup, but not in the assertion. The runtime check found this. I corrected the assertion, and the file passes. - `heartbeat-plugin-environment` failed one wait in the full run. It passed three times alone, so I think that load caused the failure. It can fail again under load. - `dot-runner` skipped all 54 tests in the full run because `cargo` was not on my `PATH`. It then passed 54 of 54 with the toolchain on the `PATH`. - My first `lib` value removed the default DOM types, and the error count went up by 375. I added the DOM libraries. - My Daytona stub with bare `any` left 48 errors, because generic helpers then inferred `unknown`. I added shapes that return promises. - One fix to `agent-secrets-routes` used `class_3_static_lease`, and the test failed. That class allows only specific paths. I reverted to `unclassified`. - `ci / General tests (server (8/12))` failed on `259737b700` because of the flaky port in `idle-completed-history`. paperclipai/paperclip#18853 fixed this test on master, so this pull request keeps that fix. **Audit of the diff.** I counted these patterns in added and removed lines, to find fixes that only hide an error: | Pattern | Added | Removed | | --- | --- | --- | | `@ts-ignore` | 0 | 0 | | `@ts-expect-error` | 0 | 1 | | `.skip` | 0 | 0 | | `as any` | 9 | 9 | | `: any` | 11 | 2 | | `as never` | 8 | 2 | | `as unknown as` | 35 | 4 | | `Promise<unknown>` | 16 | 5 | | `expect(` | 128 | 113 | No hunk removes more `expect(` calls than it adds. Three removals of test content were intentional, and I checked each one: - `muse-control` removed `signalToken`. Line 1012 already asserts that it is absent. - `merged-pr-confirmation-sweep` removed legacy aliases. Other tests cover them. - `heartbeat-workspace-branch-containment` removed a `finalize` branch that no test row can reach. Some partial fixtures stay unchecked through `as unknown as` and `Promise<unknown>`, mostly in `issue-agent-mutation-ownership-routes` and `issue-comment-reopen-routes`. **Accuracy of the check.** One program over the tree and the three shards reported the same errors at the same positions. Memory, as the peak of the largest process on one thread, was 3.93 GiB for one program and 2.43 GiB for the largest shard. I measured these two values before the fixes. Not run or not proven: - I did not run the full `pnpm test:run`, or a root `pnpm build`. I expect CI to run the full suites. - I did not run the 4 GiB container check, or the full `scripts/typecheck-low-memory.mjs`. The peaks above come from macOS, so they are not a Linux cgroup measurement. - I did not run the UI typecheck after the merges. - `workspace-runtime-https-live-exercise` is skipped, so its `cleanup` fix did not run. ## Risks - **A large diff in test files.** 328 files change. A pull request that edits the same tests can get merge conflicts. New tests on master can also add type errors before this merges. Any such error fails this check and needs a fix here. - **A higher cost for changes to source types.** A change to a type can add errors in test files that the author did not touch. The author must then fix them. This is the purpose of the check, but it is new work. - **Changed test behavior.** Some tests now run paths that they did not run before, such as the 9 chat wizard fixtures and the 3 span tests. They pass here, but they can be more sensitive to timing or to the environment. - **The Daytona stub can go stale.** The stub is written by hand. If the plugin uses a new SDK member, the typecheck reports an error until someone updates the stub. - **The release path.** `release-verify.yml` and `scripts/release.sh` run `pnpm -r typecheck`, so they now run this check. - **The tsconfig change.** The test transform reads `server/src/__tests__/tsconfig.json`. The options that I changed are for type checks, and the runs above passed. - **A gap that remains.** Tsconfigs in `packages/paperclip-runner` and in most sandbox provider plugins exclude `*.test.ts`. This check does not read most of those test files, so they can still drift. That work is separate from this pull request. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used Anthropic Claude Opus 5.5 (`claude-opus-5-5`) through Claude Code, with reasoning, tool use, code execution, and subagents. The runtime does not show the context window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass (7 tests fail locally, with and without this change. See Verification.) - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
590 lines
24 KiB
TypeScript
590 lines
24 KiB
TypeScript
/**
|
|
* PAP-17419 end-to-end regression: a leased HTTPS app/HMR pair is never handed
|
|
* to another execution workspace.
|
|
*
|
|
* The pure mediation rules are covered in
|
|
* `services/runtime-exposure/port-reservation.test.ts`. This file drives the
|
|
* *wired* path against a real database, so the persisted-lease query, the
|
|
* allocator, the ownership gate, and the startup reconciliation sweep are all
|
|
* exercised as they actually run — the layer where PAP-17251 failed.
|
|
*
|
|
* Reproduces the finding: workspace `b7ce28b4` held `42001/52001` under an open
|
|
* lease. Its backend was stopped and its exposure torn down, so the row read
|
|
* `stopped` with `exposure.state = "removed"` and an emptied `listeners` array,
|
|
* and nothing on the allocation path could still see the reservation. The
|
|
* unrelated workspace `PAP-16986-add-posthog-mcp` was then handed the pair.
|
|
*
|
|
* ## Host safety
|
|
*
|
|
* The broker is a fake, so no Tailscale Serve state is ever read or mutated.
|
|
* Allocation is driven by an injected `isPortAvailable` that models a synthetic
|
|
* host, and the only ports it will ever return are two app/HMR pairs the suite
|
|
* selects at run time: `beforeEach` scans upward from
|
|
* `RUNTIME_EXPOSURE_SUITE_APP_PORT_START` and keeps the two lowest pairs that
|
|
* read free on the real loopback host at that moment. The suite never pins a
|
|
* fixed host port as a constant, so a short-lived socket that another process
|
|
* holds on the runner cannot make this suite fail. The scan never takes the
|
|
* low lane at the bottom of the dedicated range: a real instance can hold a
|
|
* pair there under an open lease with no listener bound, which is the exact
|
|
* incident this file reproduces, so a scan that starts there could seize a
|
|
* pair a live instance still owns. The scan also rejects a port that any
|
|
* local Paperclip instance's on-disk service registry still names, even with
|
|
* no listener bound — the same open-lease shape, for a real instance instead
|
|
* of this suite's own fixture, which a listener-only probe cannot see. Guests
|
|
* do bind the two selected pairs on loopback, so the readiness and exposure
|
|
* lifecycle is exercised for real; they are reaped in `afterEach`. A pair
|
|
* that reads free at discovery can still be taken by another process before
|
|
* the guest binds it; this suite does not close that window. `PAPERCLIP_HOME`
|
|
* is redirected to a temp dir so the local-service registry never touches the
|
|
* real instance on this host.
|
|
*/
|
|
import { randomUUID } from "node:crypto";
|
|
import type { Dirent } from "node:fs";
|
|
import fs from "node:fs/promises";
|
|
import net from "node:net";
|
|
import os from "node:os";
|
|
import path from "node:path";
|
|
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
|
|
import {
|
|
activityLog,
|
|
companies,
|
|
createDb,
|
|
executionWorkspaces,
|
|
projectWorkspaces,
|
|
projects,
|
|
workspaceRuntimeServices,
|
|
type Db,
|
|
} from "@paperclipai/db";
|
|
import { eq } from "drizzle-orm";
|
|
import {
|
|
deriveViteHmrPort,
|
|
RUNTIME_EXPOSURE_APP_PORT_MAX,
|
|
RUNTIME_EXPOSURE_APP_PORT_MIN,
|
|
RUNTIME_EXPOSURE_HMR_PORT_OFFSET,
|
|
} from "@paperclipai/shared";
|
|
|
|
import type { BrokerClient, BrokerListenerRequest } from "../services/runtime-exposure/broker-client.js";
|
|
import { readListenerBindFacts } from "../services/runtime-exposure/loopback-listener.js";
|
|
import {
|
|
reconcilePersistedRuntimeServicesOnStartup,
|
|
resetRuntimeServicesForTests,
|
|
setWorkspaceRuntimeExposureDepsForTests,
|
|
startRuntimeServicesForWorkspaceControl,
|
|
} from "../services/workspace-runtime.js";
|
|
import {
|
|
getEmbeddedPostgresTestSupport,
|
|
startEmbeddedPostgresTestDatabase,
|
|
} from "./helpers/embedded-postgres.js";
|
|
|
|
/**
|
|
* The first app port this suite may select. A real instance can hold a pair
|
|
* in the low lane, at `RUNTIME_EXPOSURE_APP_PORT_MIN`, under an open lease
|
|
* with no listener bound — the exact incident this file reproduces. The scan
|
|
* must start clear of that lane, so this suite never seizes a pair a live
|
|
* instance still owns.
|
|
*/
|
|
const RUNTIME_EXPOSURE_SUITE_APP_PORT_START = RUNTIME_EXPOSURE_APP_PORT_MIN + 500;
|
|
|
|
/**
|
|
* The pair lane B holds under an open lease, and the next pair a correct
|
|
* allocator must relocate to. `beforeEach` discovers both on the real host, so
|
|
* a fixed constant here can never lose a race with a short-lived socket
|
|
* elsewhere on the runner.
|
|
*/
|
|
let LEASED_APP_PORT: number;
|
|
let LEASED_HMR_PORT: number;
|
|
let NEXT_APP_PORT: number;
|
|
let NEXT_HMR_PORT: number;
|
|
|
|
/**
|
|
* The real, unredirected Paperclip home directory. `beforeEach` later points
|
|
* `PAPERCLIP_HOME` at a throwaway temp dir for the suite under test, so this
|
|
* must be read before that happens. Mirrors the default in
|
|
* `resolvePaperclipHomeDir`.
|
|
*/
|
|
const REAL_PAPERCLIP_HOME = process.env.PAPERCLIP_TEST_HOST_HOME?.trim()
|
|
|| process.env.PAPERCLIP_HOME?.trim()
|
|
|| path.join(os.homedir(), ".paperclip");
|
|
|
|
/**
|
|
* Every port a local Paperclip instance's on-disk service registry currently
|
|
* records, read once per case from the real, unredirected Paperclip home. A
|
|
* registry record survives a stopped process with no listener, so it can
|
|
* still name the port even after the exact "listener-free lease" condition
|
|
* this suite reproduces. A listener-only scan cannot see that: it would treat
|
|
* the port as free and let the suite's own guest bind it, which can then
|
|
* block the owning instance when it resumes.
|
|
*/
|
|
async function readLocallyLeasedPorts(): Promise<Set<number>> {
|
|
const leased = new Set<number>();
|
|
const instancesDir = path.join(REAL_PAPERCLIP_HOME, "instances");
|
|
let instanceEntries: Dirent[];
|
|
try {
|
|
instanceEntries = await fs.readdir(instancesDir, { withFileTypes: true });
|
|
} catch {
|
|
return leased;
|
|
}
|
|
for (const instanceEntry of instanceEntries) {
|
|
if (!instanceEntry.isDirectory()) continue;
|
|
const registryDir = path.join(instancesDir, instanceEntry.name, "runtime-services");
|
|
let recordEntries: Dirent[];
|
|
try {
|
|
recordEntries = await fs.readdir(registryDir, { withFileTypes: true });
|
|
} catch {
|
|
continue;
|
|
}
|
|
for (const recordEntry of recordEntries) {
|
|
if (!recordEntry.isFile() || !recordEntry.name.endsWith(".json")) continue;
|
|
try {
|
|
const raw = JSON.parse(
|
|
await fs.readFile(path.join(registryDir, recordEntry.name), "utf8"),
|
|
) as { port?: unknown };
|
|
if (typeof raw.port !== "number") continue;
|
|
leased.add(raw.port);
|
|
// The registry records only the app port a managed process bound. Its
|
|
// Vite HMR companion is the same fixed offset away and is leased too.
|
|
leased.add(raw.port + RUNTIME_EXPOSURE_HMR_PORT_OFFSET);
|
|
} catch {
|
|
continue;
|
|
}
|
|
}
|
|
}
|
|
return leased;
|
|
}
|
|
|
|
/**
|
|
* A real loopback bind probe, matching production's `isLoopbackPortAvailable`
|
|
* and the identical helper in `workspace-runtime-exposure.test.ts`, plus the
|
|
* `locallyLeasedPorts` check above that a listener probe alone cannot make.
|
|
*/
|
|
async function isLoopbackPortFree(port: number, locallyLeasedPorts: Set<number>): Promise<boolean> {
|
|
if (locallyLeasedPorts.has(port)) return false;
|
|
|
|
const facts = await readListenerBindFacts(port);
|
|
if (facts?.present) return false;
|
|
|
|
return await new Promise<boolean>((resolve) => {
|
|
const probe = net.createServer();
|
|
probe.unref();
|
|
probe.once("error", () => resolve(false));
|
|
probe.listen(port, "127.0.0.1", () => {
|
|
probe.close(() => resolve(true));
|
|
});
|
|
});
|
|
}
|
|
|
|
/**
|
|
* The first app port at or above `startAt` whose HMR companion is also free on
|
|
* the real host right now, mirroring the allocator's own scan.
|
|
*/
|
|
async function findFreeExposureAppPort(startAt: number, locallyLeasedPorts: Set<number>): Promise<number> {
|
|
for (let appPort = startAt; appPort <= RUNTIME_EXPOSURE_APP_PORT_MAX; appPort += 1) {
|
|
if (
|
|
await isLoopbackPortFree(appPort, locallyLeasedPorts)
|
|
&& await isLoopbackPortFree(deriveViteHmrPort(appPort), locallyLeasedPorts)
|
|
) {
|
|
return appPort;
|
|
}
|
|
}
|
|
throw new Error("no free app/HMR port pair available in the dedicated runtime exposure range");
|
|
}
|
|
|
|
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
|
|
|
|
/**
|
|
* A synthetic host on which only the two dedicated pairs above are usable.
|
|
*
|
|
* Crucially, the leased pair reads FREE — no listener, because lane B is
|
|
* stopped. That is the exact condition under which the old allocator handed it
|
|
* away, so a fixture that reported it busy would not reproduce the bug at all.
|
|
*/
|
|
async function isPortAvailableOnSyntheticHost(port: number): Promise<boolean> {
|
|
return port === LEASED_APP_PORT || port === LEASED_HMR_PORT
|
|
|| port === NEXT_APP_PORT || port === NEXT_HMR_PORT;
|
|
}
|
|
|
|
function createFakeBroker() {
|
|
const calls: string[] = [];
|
|
const reservedByHandle = new Map<string, BrokerListenerRequest[]>();
|
|
const exposedByRuntimeId = new Map<string, BrokerListenerRequest[]>();
|
|
/** Mappings attributed to a runtime this server did not reserve. */
|
|
const foreignListeners: Array<{ runtimeId: string; port: number; purpose: "app" | "vite_hmr" }> = [];
|
|
|
|
const broker: BrokerClient = {
|
|
async reserve(runtimeId, requested) {
|
|
calls.push(`reserve:${requested.map((listener) => listener.port).join(",")}`);
|
|
const handle = `handle-${runtimeId}`;
|
|
reservedByHandle.set(handle, requested);
|
|
return { handle, reservedPorts: requested.map((listener) => listener.port) };
|
|
},
|
|
async expose(runtimeId, handle) {
|
|
calls.push("expose");
|
|
const requested = reservedByHandle.get(handle) ?? [];
|
|
exposedByRuntimeId.set(runtimeId, requested);
|
|
return { handle, publicPorts: requested.map((listener) => listener.port) };
|
|
},
|
|
async remove(runtimeId, handle) {
|
|
calls.push(`remove:${runtimeId}`);
|
|
const listeners = exposedByRuntimeId.get(runtimeId) ?? reservedByHandle.get(handle) ?? [];
|
|
exposedByRuntimeId.delete(runtimeId);
|
|
reservedByHandle.delete(handle);
|
|
return { removedPorts: listeners.map((listener) => listener.port) };
|
|
},
|
|
async list() {
|
|
return [
|
|
...foreignListeners,
|
|
...[...exposedByRuntimeId.entries()].flatMap(([runtimeId, listeners]) =>
|
|
listeners.map((listener) => ({ runtimeId, port: listener.port, purpose: listener.purpose })),
|
|
),
|
|
];
|
|
},
|
|
};
|
|
|
|
return { broker, calls, foreignListeners };
|
|
}
|
|
|
|
function installDeps(broker: BrokerClient, overrides?: {
|
|
isPortAvailable?: (port: number) => Promise<boolean>;
|
|
}) {
|
|
setWorkspaceRuntimeExposureDepsForTests({
|
|
broker,
|
|
isPortAvailable: overrides?.isPortAvailable ?? isPortAvailableOnSyntheticHost,
|
|
isBrokerAvailable: async () => true,
|
|
resolveHostname: async () => "runner.tail123.ts.net",
|
|
probeHealth: async () => true,
|
|
now: () => new Date().toISOString(),
|
|
// Loopback-bind diagnosis is covered by `workspace-runtime-exposure.test.ts`
|
|
// against real guests; stubbing it here keeps these cases about ownership.
|
|
diagnoseListenerBinds: async () => null,
|
|
});
|
|
}
|
|
|
|
const DECLARED_EXPOSE = {
|
|
type: "tailscale_https",
|
|
hostname: "auto",
|
|
publicPort: "same",
|
|
includePaperclipViteHmr: true,
|
|
failurePolicy: "fail_closed",
|
|
} as const;
|
|
|
|
/**
|
|
* A backend that binds its allocated app port and the HMR companion on
|
|
* loopback, matching the real managed lane. Readiness then has a real listener
|
|
* to probe, so the lifecycle runs to `ready` exactly as in production.
|
|
*/
|
|
// Use the test runner's executable. A login shell can resolve bare `node` to
|
|
// another installation. Keep startup facts in the service log so a readiness
|
|
// failure identifies which executable started and which ports it bound.
|
|
const guestNode = `'${process.execPath.replace(/'/g, "'\\''")}'`;
|
|
const GUEST_COMMAND =
|
|
`${guestNode} -e "const http=require('node:http');const p=Number(process.env.PORT);`
|
|
+ "console.log('guest-start',process.execPath,p);"
|
|
+ "for(const q of [p,p+10000])http.createServer((_,r)=>{r.statusCode=200;r.end('ok')}).listen(q,'127.0.0.1',()=>console.log('guest-listening',q));"
|
|
+ "setInterval(()=>{},1000)\"";
|
|
|
|
(embeddedPostgresSupport.supported ? describe : describe.skip)(
|
|
"PAP-17419 leased exposure pair reservation",
|
|
() => {
|
|
let db: Db;
|
|
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
|
let previousHttpsMode: string | undefined;
|
|
let previousPaperclipHome: string | undefined;
|
|
let previousInstanceId: string | undefined;
|
|
/**
|
|
* An EMPTY workspace root, never the repo checkout.
|
|
*
|
|
* Pointing `cwd` at the real repo makes the start path do git and
|
|
* dependency-provisioning work on a large tree, which is slow enough to
|
|
* blow the test timeout and has nothing to do with what is under test.
|
|
*/
|
|
let workspaceRoot: string;
|
|
let paperclipHome: string;
|
|
|
|
beforeAll(async () => {
|
|
tempDb = await startEmbeddedPostgresTestDatabase("pap17419-reservation-");
|
|
db = createDb(tempDb.connectionString);
|
|
previousHttpsMode = process.env.PAPERCLIP_MANAGED_RUNTIME_HTTPS;
|
|
process.env.PAPERCLIP_MANAGED_RUNTIME_HTTPS = "auto";
|
|
}, 60_000);
|
|
|
|
beforeEach(async () => {
|
|
// Discover two verified-free pairs on the real host right before each
|
|
// case runs, so the window between the probe and the guest bind stays
|
|
// as short as possible.
|
|
const locallyLeasedPorts = await readLocallyLeasedPorts();
|
|
LEASED_APP_PORT = await findFreeExposureAppPort(RUNTIME_EXPOSURE_SUITE_APP_PORT_START, locallyLeasedPorts);
|
|
LEASED_HMR_PORT = deriveViteHmrPort(LEASED_APP_PORT);
|
|
NEXT_APP_PORT = await findFreeExposureAppPort(LEASED_APP_PORT + 1, locallyLeasedPorts);
|
|
NEXT_HMR_PORT = deriveViteHmrPort(NEXT_APP_PORT);
|
|
|
|
workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pap17419-workspace-"));
|
|
paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "pap17419-home-"));
|
|
// Redirect the local-service registry into a throwaway instance. Without
|
|
// this the suite would write runtime-service records into the real
|
|
// Paperclip instance on this host and could confuse a live server.
|
|
previousPaperclipHome = process.env.PAPERCLIP_HOME;
|
|
previousInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
|
|
process.env.PAPERCLIP_HOME = paperclipHome;
|
|
process.env.PAPERCLIP_INSTANCE_ID = `pap17419-${randomUUID()}`;
|
|
});
|
|
|
|
afterAll(async () => {
|
|
if (previousHttpsMode === undefined) delete process.env.PAPERCLIP_MANAGED_RUNTIME_HTTPS;
|
|
else process.env.PAPERCLIP_MANAGED_RUNTIME_HTTPS = previousHttpsMode;
|
|
await tempDb?.cleanup();
|
|
});
|
|
|
|
afterEach(async () => {
|
|
// Terminate first, while the suite's fake broker is still installed.
|
|
await resetRuntimeServicesForTests({ terminateProcesses: true });
|
|
if (previousPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
|
|
else process.env.PAPERCLIP_HOME = previousPaperclipHome;
|
|
if (previousInstanceId === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
|
|
else process.env.PAPERCLIP_INSTANCE_ID = previousInstanceId;
|
|
await fs.rm(workspaceRoot, { recursive: true, force: true });
|
|
await fs.rm(paperclipHome, { recursive: true, force: true });
|
|
await db.delete(workspaceRuntimeServices);
|
|
await db.delete(executionWorkspaces);
|
|
await db.delete(projectWorkspaces);
|
|
await db.delete(projects);
|
|
// Drift reporting writes activity rows, which hold a company FK.
|
|
await db.delete(activityLog);
|
|
await db.delete(companies);
|
|
});
|
|
|
|
/**
|
|
* Seed the incident's two workspaces: lane B with an open lease and a
|
|
* stopped, torn-down runtime row on the leased pair, and the unrelated
|
|
* workspace that will ask for a pair next.
|
|
*/
|
|
async function seedIncident(options?: { leaseStatus?: string; leasedRowStatus?: string }) {
|
|
const companyId = randomUUID();
|
|
const projectId = randomUUID();
|
|
const projectWorkspaceId = randomUUID();
|
|
const leasedWorkspaceId = randomUUID();
|
|
const otherWorkspaceId = randomUUID();
|
|
const leasedRuntimeId = randomUUID();
|
|
|
|
await db.insert(companies).values({
|
|
id: companyId,
|
|
name: "Paperclip",
|
|
issuePrefix: `Q${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
|
|
requireBoardApprovalForNewAgents: false,
|
|
});
|
|
await db.insert(projects).values({ id: projectId, companyId, name: "Paperclip App", status: "in_progress" });
|
|
await db.insert(projectWorkspaces).values({
|
|
id: projectWorkspaceId,
|
|
companyId,
|
|
projectId,
|
|
name: "Primary",
|
|
cwd: workspaceRoot,
|
|
isPrimary: true,
|
|
});
|
|
for (const [id, name] of [[leasedWorkspaceId, "lane-b"], [otherWorkspaceId, "posthog-mcp"]] as const) {
|
|
await db.insert(executionWorkspaces).values({
|
|
id,
|
|
companyId,
|
|
projectId,
|
|
projectWorkspaceId,
|
|
mode: "isolated_workspace",
|
|
strategyType: "git_worktree",
|
|
name,
|
|
// Lane B's lease is open unless a case closes it.
|
|
status: id === leasedWorkspaceId ? (options?.leaseStatus ?? "active") : "active",
|
|
closedAt: id === leasedWorkspaceId && options?.leaseStatus === "archived" ? new Date() : null,
|
|
cwd: workspaceRoot,
|
|
baseRef: "HEAD",
|
|
branchName: name,
|
|
providerType: "git_worktree",
|
|
});
|
|
}
|
|
|
|
// Lane B as the incident left it: stopped, torn down, `removed` — and an
|
|
// EMPTY listeners array, which is what `deprovisionExposure` writes. The
|
|
// `port` column is the only surviving record of the leased pair.
|
|
await db.insert(workspaceRuntimeServices).values({
|
|
id: leasedRuntimeId,
|
|
companyId,
|
|
projectId,
|
|
projectWorkspaceId,
|
|
executionWorkspaceId: leasedWorkspaceId,
|
|
scopeType: "execution_workspace",
|
|
scopeId: leasedWorkspaceId,
|
|
serviceName: "preview",
|
|
status: options?.leasedRowStatus ?? "stopped",
|
|
lifecycle: "shared",
|
|
command: GUEST_COMMAND,
|
|
cwd: workspaceRoot,
|
|
port: LEASED_APP_PORT,
|
|
provider: "local_process",
|
|
exposure: {
|
|
provider: "tailscale_https",
|
|
state: "removed",
|
|
publicUrl: null,
|
|
hostname: null,
|
|
listeners: [],
|
|
brokerRef: null,
|
|
lastError: null,
|
|
updatedAt: new Date().toISOString(),
|
|
},
|
|
stoppedAt: new Date(),
|
|
});
|
|
|
|
return { companyId, projectId, projectWorkspaceId, leasedWorkspaceId, otherWorkspaceId, leasedRuntimeId };
|
|
}
|
|
|
|
function startInput(seed: Awaited<ReturnType<typeof seedIncident>>, executionWorkspaceId: string) {
|
|
return {
|
|
invocationId: "pap-17419-reservation",
|
|
actor: { id: null, name: "Paperclip", companyId: seed.companyId },
|
|
issue: null,
|
|
db,
|
|
workspace: {
|
|
baseCwd: workspaceRoot,
|
|
source: "project_primary" as const,
|
|
projectId: seed.projectId,
|
|
workspaceId: seed.projectWorkspaceId,
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
strategy: "project_primary" as const,
|
|
cwd: workspaceRoot,
|
|
branchName: "test",
|
|
branchCreatedByRuntime: false,
|
|
worktreePath: null,
|
|
warnings: [],
|
|
created: false,
|
|
},
|
|
executionWorkspaceId,
|
|
config: {
|
|
workspaceRuntime: {
|
|
services: [{
|
|
name: "preview",
|
|
command: GUEST_COMMAND,
|
|
port: { type: "auto", envKey: "PORT" },
|
|
readiness: { type: "http", urlTemplate: "http://127.0.0.1:{{port}}", timeoutSec: 10, intervalMs: 50 },
|
|
expose: DECLARED_EXPOSE,
|
|
}],
|
|
},
|
|
},
|
|
adapterEnv: {},
|
|
};
|
|
}
|
|
|
|
it("regression 1: does not hand a stopped-but-leased pair to another workspace", async () => {
|
|
const seed = await seedIncident();
|
|
const { broker, calls } = createFakeBroker();
|
|
installDeps(broker);
|
|
|
|
const [runtime] = await startRuntimeServicesForWorkspaceControl(
|
|
startInput(seed, seed.otherWorkspaceId),
|
|
);
|
|
|
|
// The incident outcome would be LEASED_APP_PORT here.
|
|
expect(runtime.port).toBe(NEXT_APP_PORT);
|
|
expect(runtime.port).not.toBe(LEASED_APP_PORT);
|
|
expect(runtime.url).toBe(`https://runner.tail123.ts.net:${NEXT_APP_PORT}`);
|
|
// The broker was never even asked to reserve the leased pair.
|
|
expect(calls.filter((call) => call.includes(String(LEASED_APP_PORT)))).toEqual([]);
|
|
expect(calls[0]).toBe(`reserve:${NEXT_APP_PORT},${NEXT_HMR_PORT}`);
|
|
}, 30_000);
|
|
|
|
it("regression 1: fails closed rather than reusing the leased pair when it is the only one left", async () => {
|
|
const seed = await seedIncident();
|
|
const { broker, calls } = createFakeBroker();
|
|
// A host on which the leased pair is the only free pair in the range.
|
|
installDeps(broker, {
|
|
isPortAvailable: async (port) => port === LEASED_APP_PORT || port === LEASED_HMR_PORT,
|
|
});
|
|
|
|
await expect(startRuntimeServicesForWorkspaceControl(
|
|
startInput(seed, seed.otherWorkspaceId),
|
|
)).rejects.toThrow(/no free app\/HMR port pair available/);
|
|
|
|
expect(calls).toEqual([]);
|
|
}, 30_000);
|
|
|
|
it("regression 1: lets the leaseholder's own workspace take its pair back", async () => {
|
|
const seed = await seedIncident();
|
|
const { broker } = createFakeBroker();
|
|
installDeps(broker);
|
|
|
|
const [runtime] = await startRuntimeServicesForWorkspaceControl(
|
|
startInput(seed, seed.leasedWorkspaceId),
|
|
);
|
|
|
|
// Same workspace, so the preserved-port preference still applies.
|
|
expect(runtime.port).toBe(LEASED_APP_PORT);
|
|
}, 30_000);
|
|
|
|
it("regression 3: denies a pair whose Serve mapping belongs to another runtime", async () => {
|
|
const seed = await seedIncident();
|
|
const { broker, foreignListeners } = createFakeBroker();
|
|
// The pair the allocator would otherwise relocate to is already published
|
|
// by a runtime this server has no row for — the unattributable case.
|
|
foreignListeners.push({ runtimeId: "runtime-not-ours", port: NEXT_APP_PORT, purpose: "app" });
|
|
installDeps(broker);
|
|
|
|
await expect(startRuntimeServicesForWorkspaceControl(
|
|
startInput(seed, seed.otherWorkspaceId),
|
|
)).rejects.toThrow(/no free app\/HMR port pair available|HTTPS exposure allocation denied/);
|
|
}, 30_000);
|
|
|
|
it("regression 5: release makes the pair reusable by a different workspace", async () => {
|
|
const seed = await seedIncident({ leaseStatus: "archived" });
|
|
const { broker } = createFakeBroker();
|
|
installDeps(broker);
|
|
|
|
const [runtime] = await startRuntimeServicesForWorkspaceControl(
|
|
startInput(seed, seed.otherWorkspaceId),
|
|
);
|
|
|
|
// Lane B's lease is released, so its pair is genuinely free again and the
|
|
// ascending scan hands out the lowest one.
|
|
expect(runtime.port).toBe(LEASED_APP_PORT);
|
|
}, 30_000);
|
|
|
|
it("regression 3: reconciliation surfaces a removed row whose pair is mapped elsewhere, and adopts nothing", async () => {
|
|
const seed = await seedIncident();
|
|
const { broker, foreignListeners, calls } = createFakeBroker();
|
|
// Lane B reads `stopped`/`removed`, but the host still publishes its pair
|
|
// for someone else. Exactly the falsely-attributed state from PAP-17251.
|
|
foreignListeners.push({ runtimeId: "runtime-not-ours", port: LEASED_APP_PORT, purpose: "app" });
|
|
installDeps(broker);
|
|
|
|
const result = await reconcilePersistedRuntimeServicesOnStartup(db);
|
|
|
|
expect(result.exposureReservationDrift).toHaveLength(1);
|
|
expect(result.exposureReservationDrift[0]).toMatchObject({
|
|
runtimeServiceId: seed.leasedRuntimeId,
|
|
port: LEASED_APP_PORT,
|
|
reason: "serve_mapping",
|
|
owner: { executionWorkspaceId: seed.leasedWorkspaceId },
|
|
conflictingOwner: { runtimeServiceId: "runtime-not-ours" },
|
|
});
|
|
// The occupying mapping is left strictly alone: no removal, no adoption.
|
|
expect(calls.filter((call) => call.startsWith("remove"))).toEqual([]);
|
|
|
|
const [row] = await db
|
|
.select()
|
|
.from(workspaceRuntimeServices)
|
|
.where(eq(workspaceRuntimeServices.id, seed.leasedRuntimeId));
|
|
expect(row!.status).toBe("stopped");
|
|
expect(row!.port).toBe(LEASED_APP_PORT);
|
|
}, 30_000);
|
|
|
|
it("regression 4: concurrent starts in different workspaces never share a pair", async () => {
|
|
const seed = await seedIncident({ leaseStatus: "archived" });
|
|
const { broker } = createFakeBroker();
|
|
installDeps(broker);
|
|
|
|
const [first, second] = await Promise.all([
|
|
startRuntimeServicesForWorkspaceControl(startInput(seed, seed.otherWorkspaceId)),
|
|
startRuntimeServicesForWorkspaceControl(startInput(seed, seed.leasedWorkspaceId)),
|
|
]);
|
|
|
|
const ports = [first[0]?.port, second[0]?.port].sort();
|
|
expect(ports).toEqual([LEASED_APP_PORT, NEXT_APP_PORT]);
|
|
}, 30_000);
|
|
},
|
|
);
|