Skip to content
Merged
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
2 changes: 1 addition & 1 deletion .github/actions/e2e-setup/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: |
runs:
using: composite
steps:
# E2E port configuration (slot 0 defaults — must match scripts/test-e2e.sh)
# E2E port configuration (slot 0 defaults — must match scripts/slots.sh)
- name: Set E2E environment variables
shell: bash
run: |
Expand Down
40 changes: 18 additions & 22 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,20 @@ include .env
# ---------------------------------------------------------------------------
# Multi-agent / worktree isolation
# ---------------------------------------------------------------------------
# Compute a deterministic port offset (0-99) from the working directory name
# so that multiple worktrees can run integration tests in parallel without
# port conflicts. Override HDX_CI_SLOT manually if you need a specific slot.
#
# Port mapping (base + slot):
# ClickHouse HTTP : 18123 + slot
# MongoDB : 39999 + slot
# API test server : 19000 + slot
# OpAMP : 14320 + slot
# Integration tests get a slot and ports per worktree so they can run in
# parallel. scripts/slots.sh computes them; override the slot with
# `make dev-int HDX_CI_SLOT=5`.
# ---------------------------------------------------------------------------
HDX_CI_SLOT ?= $(shell printf '%s' "$(notdir $(CURDIR))" | cksum | awk '{print $$1 % 100}')
HDX_CI_PROJECT := int-$(HDX_CI_SLOT)
HDX_CI_CH_PORT := $(shell echo $$((18123 + $(HDX_CI_SLOT))))
HDX_CI_MONGO_PORT:= $(shell echo $$((39999 + $(HDX_CI_SLOT))))
HDX_CI_API_PORT := $(shell echo $$((19000 + $(HDX_CI_SLOT))))
HDX_CI_OPAMP_PORT:= $(shell echo $$((14320 + $(HDX_CI_SLOT))))
# One shell for all six values: this runs on every make invocation, and each
# shell costs ~20ms.
_hdx_ci := $(shell HDX_CI_SLOT='$(HDX_CI_SLOT)' sh -c '. ./scripts/slots.sh && hdx_ci_ports && echo "$$HDX_CI_SLOT $$HDX_CI_PROJECT $$HDX_CI_CH_PORT $$HDX_CI_MONGO_PORT $$HDX_CI_API_PORT $$HDX_CI_OPAMP_PORT"')

HDX_CI_SLOT := $(word 1,$(_hdx_ci))
HDX_CI_PROJECT := $(word 2,$(_hdx_ci))
HDX_CI_CH_PORT := $(word 3,$(_hdx_ci))
HDX_CI_MONGO_PORT:= $(word 4,$(_hdx_ci))
HDX_CI_API_PORT := $(word 5,$(_hdx_ci))
HDX_CI_OPAMP_PORT:= $(word 6,$(_hdx_ci))

export HDX_CI_CH_PORT HDX_CI_MONGO_PORT HDX_CI_API_PORT HDX_CI_OPAMP_PORT

Expand Down Expand Up @@ -135,9 +133,9 @@ dev-int-down:

.PHONY: dev-e2e-down
dev-e2e-down:
$(eval HDX_E2E_SLOT := $(shell printf '%s' "$(notdir $(CURDIR))" | cksum | awk '{print $$1 % 100}'))
docker compose -p e2e-$(HDX_E2E_SLOT) -f packages/app/tests/e2e/docker-compose.yml down -v
@for port in $$((21000 + $(HDX_E2E_SLOT))) $$((20320 + $(HDX_E2E_SLOT))) $$((21300 + $(HDX_E2E_SLOT))) $$((21200 + $(HDX_E2E_SLOT))); do \
@. ./scripts/slots.sh && hdx_e2e_ports && \
docker compose -p "$$E2E_PROJECT" -f packages/app/tests/e2e/docker-compose.yml down -v && \
for port in $$HDX_E2E_API_PORT $$HDX_E2E_OPAMP_PORT $$HDX_E2E_APP_PORT $$HDX_E2E_APP_LOCAL_PORT; do \
pids=$$(lsof -ti :$$port 2>/dev/null); \
for pid in $$pids; do \
echo "Killing process $$pid on port $$port"; \
Expand Down Expand Up @@ -196,6 +194,7 @@ ci-unit:
node --test .github/scripts/__tests__/release-notes.test.mjs
node --test .github/scripts/__tests__/changeset-hash.test.mjs
node --test .github/scripts/code-review/__tests__/review-comments.test.mjs
node --test scripts/__tests__/slots.test.mjs

.PHONY: ci-triage
ci-triage:
Expand All @@ -205,9 +204,6 @@ ci-triage:
# ---------------------------------------------------------------------------
# E2E tests — port isolation is handled by scripts/test-e2e.sh
# ---------------------------------------------------------------------------
# Slot for the Playwright report server (only used by the Makefile REPORT flag)
HDX_E2E_SLOT ?= $(shell printf '%s' "$(notdir $(CURDIR))" | cksum | awk '{print $$1 % 100}')

.PHONY: e2e
e2e:
./scripts/test-e2e.sh
Expand All @@ -227,7 +223,7 @@ dev-e2e-clean:
dev-e2e:
./scripts/test-e2e.sh --dev $(if $(FILE),$(FILE)) $(if $(GREP),--grep "$(GREP)") $(ARGS); \
ret=$$?; \
$(if $(REPORT),cd packages/app && npx playwright show-report --port $$((9323 + $(HDX_E2E_SLOT)));) \
$(if $(REPORT),. ./scripts/slots.sh && hdx_e2e_ports && cd packages/app && npx playwright show-report --port $$HDX_E2E_REPORT_PORT;) \
exit $$ret


Expand Down
113 changes: 72 additions & 41 deletions agent_docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,10 @@ multiple agents or developers working in parallel), use `make dev` instead of

### How It Works

1. A deterministic slot (0-99) is computed from the worktree directory name (via
`cksum`)
1. `scripts/slots.sh` computes a deterministic slot (0-99) from the worktree
directory name (via `cksum`), or from its full path with `HDX_SLOT_FROM=path`
(see below). It is the only place slots and ports are computed: `yarn dev`,
`make dev-int`, `make dev-e2e`, and tools all use it.
2. Each service gets a unique port: `base + slot` (see table below)
3. Docker Compose runs with a unique project name (`hdx-dev-<slot>`)
4. Volume paths include the slot to prevent data corruption between worktrees
Expand Down Expand Up @@ -92,6 +94,36 @@ The portal auto-refreshes every 3 seconds and shows each worktree's:
HDX_DEV_SLOT=5 make dev
```

### Worktrees With the Same Folder Name

If your worktrees share a folder name (`a/hyperdx`, `b/hyperdx`), they get the
same slot and clash. Set `HDX_SLOT_FROM=path` in your shell profile to hash each
worktree's full path instead. It applies to the dev stack, integration tests,
E2E tests, and the dev portal.

```bash
export HDX_SLOT_FROM=path
```

Your existing stacks move to new slots once, so their dev data (in
`.volumes/*_<slot>`) starts empty. The default, `HDX_SLOT_FROM=name`, keeps
today's slots.

### Tools That Talk to the Dev Stack

Run them through `scripts/with-slots.sh`. It sets this worktree's dev ports
(`HDX_DEV_CH_HTTP_PORT`, `HYPERDX_API_PORT`, ...) and nothing else. Don't source
`scripts/dev-env.sh` for this: it also clears `packages/app/.next` and registers
the stack with the dev portal, which disrupts a running `yarn dev`.

```bash
# From a package script, e.g. packages/api's "seed:alerts"
../../scripts/with-slots.sh ts-node scripts/seed-alerts.ts

# Against another slot
HDX_DEV_SLOT=5 scripts/with-slots.sh <command>
```

## Testing Strategy

### Testing Tools
Expand Down Expand Up @@ -254,65 +286,64 @@ yarn run lint
- **Controllers**: `packages/api/src/controllers/`
- **Pages**: `packages/app/pages/`
- **Components**: `packages/app/src/`
- **Shared Utils**: `packages/common-utils/src/` — no root barrel, so imports are
deep `@hyperdx/common-utils/dist/...` paths. See
[`code_style.md`](code_style.md#where-shared-code-already-lives) for the module
map and the grep-first rule before you add a helper.
- **Shared Utils**: `packages/common-utils/src/` — no root barrel, so imports
are deep `@hyperdx/common-utils/dist/...` paths. See
[`code_style.md`](code_style.md#where-shared-code-already-lives) for the
module map and the grep-first rule before you add a helper.

## Vercel Preview Deployments (Inline API)

The `hyperdx-private` Vercel project deploys the `@hyperdx/app` Next.js app
for preview environments. Normally `/api/*` requests proxy to a separately
deployed API service (`SERVER_URL`). For PR previews we instead **inline the
entire Express API** into the Next.js serverless function so a single Vercel
deployment serves both the app and the API.
The `hyperdx-private` Vercel project deploys the `@hyperdx/app` Next.js app for
preview environments. Normally `/api/*` requests proxy to a separately deployed
API service (`SERVER_URL`). For PR previews we instead **inline the entire
Express API** into the Next.js serverless function so a single Vercel deployment
serves both the app and the API.

### How it works

1. `packages/api/src/serverless.ts` exposes the Express app from
`api-app.ts` as a stateless `(req, res) => Promise<void>` handler. It
lazily connects to MongoDB on the first invocation and caches the
connection across warm invocations.
2. `packages/app/pages/api/[...all].ts` branches on the
`HDX_PREVIEW_INLINE_API` env var. When `true`, it `require()`s the
compiled serverless handler and dispatches directly. Otherwise it falls
back to the existing http-proxy-middleware path used by Docker/standalone
builds.
1. `packages/api/src/serverless.ts` exposes the Express app from `api-app.ts` as
a stateless `(req, res) => Promise<void>` handler. It lazily connects to
MongoDB on the first invocation and caches the connection across warm
invocations.
2. `packages/app/pages/api/[...all].ts` branches on the `HDX_PREVIEW_INLINE_API`
env var. When `true`, it `require()`s the compiled serverless handler and
dispatches directly. Otherwise it falls back to the existing
http-proxy-middleware path used by Docker/standalone builds.
3. `packages/app/next.config.mjs` adds a webpack `externals` rule that marks
`@hyperdx/api` as a CommonJS external **unless** `HDX_PREVIEW_INLINE_API`
is `true`. This keeps production app builds (Docker fullstack image,
standalone Next output) byte-for-byte equivalent to before — they never
bundle passport-saml, mongoose, AWS SDK, etc.
`@hyperdx/api` as a CommonJS external **unless** `HDX_PREVIEW_INLINE_API` is
`true`. This keeps production app builds (Docker fullstack image, standalone
Next output) byte-for-byte equivalent to before — they never bundle
passport-saml, mongoose, AWS SDK, etc.
4. `vercel.json` declares the repo-root build commands so Vercel builds
`common-utils` → `api` → `app` in order.

### Required Vercel project env vars (Preview scope only)

| Key | Notes |
|---|---|
| `HDX_PREVIEW_INLINE_API` | `true` — turns on the inline path |
| `MONGO_URI` | Preview MongoDB connection string |
| `EXPRESS_SESSION_SECRET` | Random 32+ char string |
| `DISABLED_AUTH_METHODS` | `google,saml` (avoids per-preview OAuth callback URL config) |
| `AI_PROVIDER`, `AI_API_KEY`, `AI_MODEL_NAME` | Optional, only if AI features should work |
| `FRONTEND_URL` | Optional. Leave unset to use host-only cookies on the preview URL |
| Key | Notes |
| -------------------------------------------- | ----------------------------------------------------------------- |
| `HDX_PREVIEW_INLINE_API` | `true` — turns on the inline path |
| `MONGO_URI` | Preview MongoDB connection string |
| `EXPRESS_SESSION_SECRET` | Random 32+ char string |
| `DISABLED_AUTH_METHODS` | `google,saml` (avoids per-preview OAuth callback URL config) |
| `AI_PROVIDER`, `AI_API_KEY`, `AI_MODEL_NAME` | Optional, only if AI features should work |
| `FRONTEND_URL` | Optional. Leave unset to use host-only cookies on the preview URL |

Production env vars on the same project must leave `HDX_PREVIEW_INLINE_API`
unset (or `false`) so production deployments keep using the proxy path.

### Limitations

- **No background tasks.** Scheduled jobs (`packages/api/src/tasks/`,
including `CheckAlertTask`) are not run in preview deployments.
- **No background tasks.** Scheduled jobs (`packages/api/src/tasks/`, including
`CheckAlertTask`) are not run in preview deployments.
- **No alerts.** Alert evaluation depends on the cron task runner.
- **No OPAMP server.** The OPAMP control-plane server (`APP_TYPE=opamp`) is
not started in preview. The serverless entrypoint asserts
`APP_TYPE=api` and refuses to boot otherwise.
- **No OPAMP server.** The OPAMP control-plane server (`APP_TYPE=opamp`) is not
started in preview. The serverless entrypoint asserts `APP_TYPE=api` and
refuses to boot otherwise.
- **Function size.** The bundled function should stay under Vercel's 50 MB
unzipped limit. If it grows, mark heavy deps (`@aws-sdk/*`,
`@node-saml/passport-saml`, AI SDKs) as `serverExternalPackages` in
`next.config.mjs`.
- **Cold-start latency.** First request after idle pays ~500–1500 ms for
the initial Mongo connection.
- **Shared preview MongoDB.** Unless you partition by database name, all
preview deployments share the same Mongo state.
- **Cold-start latency.** First request after idle pays ~500–1500 ms for the
initial Mongo connection.
- **Shared preview MongoDB.** Unless you partition by database name, all preview
deployments share the same Mongo state.
3 changes: 3 additions & 0 deletions knip.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
{
"$schema": "https://unpkg.com/knip@6/schema.json",
"workspaces": {
".": {
"entry": ["scripts/__tests__/*.test.mjs"]
},
"packages/app": {
"entry": ["pages/**/*.{ts,tsx}", "scripts/*.js", "tests/e2e/**/*.ts"],
"project": ["src/**/*.{ts,tsx}", "pages/**/*.{ts,tsx}"],
Expand Down
2 changes: 1 addition & 1 deletion packages/api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@
"dev:migrate-ch-create": "migrate create -ext sql -dir ./migrations/ch -seq",
"dev:migrate-ch": "migrate -database 'clickhouse://localhost:9000?database=default&x-multi-statement=true' -path ./migrations/ch up",
"docgen": "ts-node scripts/generate-api-docs.ts",
"seed:alerts": "ts-node --transpile-only -r tsconfig-paths/register scripts/seed-alerts.ts",
"seed:alerts": "../../scripts/with-slots.sh ts-node --transpile-only -r tsconfig-paths/register scripts/seed-alerts.ts",
"lint:openapi": "yarn docgen && spectral lint openapi.json"
}
}
33 changes: 12 additions & 21 deletions packages/api/scripts/seed-alerts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,14 @@
* yarn seed:alerts --count 2000
* yarn seed:alerts --purge
*
* The Mongo URI defaults to the dev slot of the current git worktree, derived
* the same way scripts/dev-env.sh derives it. Override with --mongo-uri or
* MONGO_URI. The dev stack must be up (`yarn dev`) and registered once, since
* The Mongo URI defaults to the dev slot of the current git worktree, from
* scripts/slots.sh. Override with --mongo-uri, MONGO_URI, or HDX_DEV_SLOT.
* The dev stack must be up (`yarn dev`) and registered once, since
* the script attaches everything to the existing team and log source.
*/
import { formatTileAlertDisplayName } from '@hyperdx/common-utils/dist/alerts';
import { DisplayType } from '@hyperdx/common-utils/dist/types';
import { execFileSync } from 'child_process';
import mongoose from 'mongoose';
import path from 'path';

import Alert, { AlertSource, AlertState } from '@/models/alert';
import Dashboard from '@/models/dashboard';
Expand Down Expand Up @@ -122,24 +120,17 @@ function parseArgs(argv: string[]): Args {
}

/**
* Mongo URI of the dev slot for the worktree this script lives in, matching
* the slot derivation in scripts/dev-env.sh (cksum of the directory name).
* Mongo URI of this worktree's dev stack. `yarn seed:alerts` runs through
* scripts/with-slots.sh, which sets HDX_DEV_MONGO_PORT.
*/
function devSlotMongoUri(): string {
const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
encoding: 'utf8',
}).trim();
const slot =
process.env.HDX_DEV_SLOT ??
execFileSync(
'sh',
['-c', `printf '%s' "$DIR" | cksum | awk '{print $1 % 100}'`],
{
encoding: 'utf8',
env: { ...process.env, DIR: path.basename(repoRoot) },
},
).trim();
return `mongodb://localhost:${30400 + Number(slot)}/hyperdx`;
const port = process.env.HDX_DEV_MONGO_PORT;
if (!port) {
throw new Error(
'HDX_DEV_MONGO_PORT is not set. Run this with `yarn seed:alerts`, or pass --mongo-uri.',
);
}
return `mongodb://localhost:${port}/hyperdx`;
}

function randomInt(minInclusive: number, maxInclusive: number): number {
Expand Down
9 changes: 4 additions & 5 deletions packages/hdx-eval/scripts/env.sh
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
#!/usr/bin/env bash
# Set up the full environment for hdx-eval, then exec the remaining args.
#
# 1. Source dev-env.sh from the monorepo root for slot-based port vars
# 1. Set the dev stack's slot-based port vars from scripts/slots.sh
# 2. Wrap the command with dotenvx to load .env / .env.local
#
# Usage:
# scripts/env.sh tsx src/cli.ts seed error-root-cause
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"

# Slot-based port env vars (HYPERDX_API_PORT, HDX_DEV_CH_HTTP_PORT, etc.)
_HDX_EVAL_CWD="$PWD"
cd "$REPO_ROOT" && source ./scripts/dev-env.sh > /dev/null 2>&1
cd "$_HDX_EVAL_CWD"
unset _HDX_EVAL_CWD
# shellcheck source=../../../scripts/slots.sh
. "$REPO_ROOT/scripts/slots.sh"
hdx_dev_ports "$REPO_ROOT"

# Load .env.local from the monorepo root (existing vars take precedence)
exec "$REPO_ROOT/node_modules/.bin/dotenvx" run \
Expand Down
Loading
Loading