perf(db): build the agent request authentication statements once per client (#21707)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - One Node process controls every run of a workspace. At 1,000
concurrent agents, main-thread CPU for each database statement is the
scarce resource.
> - A CPU profile of the hosted server shows the cost is per statement:
building SQL text in Drizzle costs about as much as parsing the result
in postgres.js.
> - Every authenticated agent API request (about 0.3 per agent per
second, plus tool calls) runs three fixed statements in
`actorMiddleware`: the agent row, the run authentication projection, and
the responsible user's company memberships. The server built the SQL
text of all three again for every request.
> - A local micro-benchmark shows that building the text is 15 to 40 µs
of CPU per statement for these shapes, and that a reused prepared query
costs the same as a raw driver call. Drizzle's `tracing.ts` wrapper is a
no-op (0.1 µs).
> - This pull request prepares the three statements once per database
client with placeholders, and executes them with the request's values.
The driver receives the same SQL text and parameters as before.
> - The benefit is about 40% less main-thread CPU for each authenticated
agent request in a local benchmark.

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The CPU cost of agent JWT and agent key authentication on every agent
API request.

**Subsystem affected**
Server request authentication (`server/src/middleware/auth.ts`,
`server/src/middleware/agent-run-authentication.ts`).

**Current behavior**
For every agent request, `actorMiddleware` builds three Drizzle queries
from scratch: `agents` by id, the `heartbeat_runs` authentication
projection (with `jsonb_build_object` and two `run_identity_contexts`
subqueries), and the `company_memberships` read with an `exists` on
`auth_users`. Building and preparing them costs 14, 38 and 40 µs of CPU
(median of 7 passes of 5,000 builds).

**Proposed behavior**
Build each statement one time for each database client, with
`sql.placeholder` values. Execute the prepared query with the request's
values. The SQL text, the parameters, and the returned rows stay the
same.

**Reason and benefit**
At 1,000 agents, agent API traffic is several hundred authenticated
requests per second on one main thread. Measured CPU per authenticated
request (local, embedded PostgreSQL, `process.cpuUsage()`, 2,000
requests per pass):

| Run (interleaved) | Before: median (min–max) µs | After: median
(min–max) µs | Load average |
| --- | --- | --- | --- |
| 1 | 436 (363–599) | 200 (183–224) | 10.8 / 10.1 |
| 2 | 489 (430–535) | 312 (212–392) | 11.6 / 13.4 |
| 3 | 461 (442–562) | 281 (247–409) | 13.1 / 12.9 |
| separate | 383 (322–810), 301 (268–476) | 169 (156–439), 193 (174–215)
| 9.5 / 9.0 |

The machine is shared (18 cores), so the spread is wide. Every pair
shows the after run lower. The drop is larger than the build cost alone,
because the request also allocates less (fewer builder objects to
collect).

**Breaking changes**
None. The statements, their parameters and the result shapes do not
change.

**Additional context**
Per-statement cost attribution from the new
`packages/db/scripts/benchmark-statement-cpu.ts` (CPU µs per statement,
median of 5 passes of 2,000, two runs, concurrency 1, load average
20–26):

| Statement | Drizzle builder | Build only (`toSQL`) | Drizzle
`.prepare()` reused | `unsafe(text, params)` | `unsafe(..., {prepare:
true})` |
| --- | --- | --- | --- | --- | --- |
| `issues` parent by id | 105 / 122 | 17 / 18 | 59 / 75 | 57 / 63 | 30 /
33 |
| `issues` full row by id | 277 / 326 | 136 / 153 | 96 / 81 | 97 / 77 |
48 / 33 |
| `company_memberships` by principal | 128 / 103 | 35 / 33 | 71 / 66 |
80 / 63 | 37 / 32 |
| join with an in-list of 10 | 169 / 173 | 57 / 57 | 83 / 88 | 109 / 80
| 42 / 40 |
| update by id | 110 / 106 | 25 / 26 | 75 / 80 | 76 / 73 | 39 / 40 |
| insert `activity_log` | 116 / 125 | 34 / 35 | 65 / 57 | 64 / 55 | 41 /
30 |

Drizzle's no-op tracer (`startActiveSpan`) measured 0.1 µs per call.

## What Changed

- `server/src/services/prepared-statements.ts`: add
`preparedStatement(prepare)`, the single-statement form of the existing
`preparedStatements` helper (one prepared query for each `Db`, held in a
`WeakMap`).
- `server/src/middleware/agent-run-authentication.ts`: split the query
into `agentRunAuthenticationQuery(db, binding)`;
`loadAgentRunAuthentication` executes the query prepared once with
placeholders.
- `server/src/middleware/auth.ts`: add `agentAuthenticationQuery` and
`responsibleUserMembershipsQuery`; the JWT path, the agent key path and
`loadResponsibleUserMemberships` execute their prepared forms.
- `server/src/__tests__/agent-auth-prepared-statements.test.ts` (new):
proves that each prepared statement sends the same SQL text and
parameters and returns strictly equal rows, and that repeated agent
requests do not build the statements again.
- `server/src/__tests__/agent-auth-middleware.test.ts`: the test
double's select chain now supports `.prepare().execute()`.
- `server/src/__tests__/prepared-statements.test.ts`: covers
`preparedStatement`.
- `packages/db/scripts/benchmark-statement-cpu.ts` (new): CPU per
statement for the builder, build only, a reused prepared query, `unsafe`
with and without `prepare: true`, and the no-op tracer. Run with `cd
packages/db && ITERATIONS=2000 PASSES=5 node --import tsx
scripts/benchmark-statement-cpu.ts` (`CONCURRENCY`, `ONLY`, `VARIANTS`
are optional).
- `scripts/benchmark-agent-request-auth-cpu.ts` (new): CPU per
authenticated agent JWT request through `actorMiddleware`. Run with
`pnpm --filter @paperclipai/server exec tsx
../scripts/benchmark-agent-request-auth-cpu.ts`.

Both benchmarks start their own embedded PostgreSQL in a temporary
directory.

## Verification

- Red/green: the "builds the request authentication statements once per
database client" test failed on `origin/master` (`select` called 12
times in 3 requests) and passes with this change.
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/agent-auth-prepared-statements.test.ts
src/__tests__/prepared-statements.test.ts
src/__tests__/agent-auth-middleware.test.ts
src/__tests__/agent-run-authentication.test.ts
src/__tests__/agent-jwt-request-authentication.test.ts
src/__tests__/auth-session-route.test.ts
src/middleware/cloud-tenant-actor.test.ts
src/__tests__/local-agent-process-boundary.test.ts
src/__tests__/liveness.test.ts src/__tests__/inbox-mine-routes.test.ts
src/__tests__/board-bootstrap-routes.test.ts
src/__tests__/agent-auth-identity-transfer.test.ts
src/__tests__/prepared-statements-driver.test.ts
src/services/fresh-continuation-fallback.test.ts`: all pass.
- CPU before and after: the tables above.

## Risks

- Low risk. The prepared query uses Drizzle's own `PgPreparedQuery`, the
same execute path that the builder uses. The test pins the SQL text, the
parameters and the rows against the builder.
- Drizzle's `.prepare(name)` on postgres.js does not send a statement
name to the database (see #21201). With `DATABASE_PREPARED_STATEMENTS`
unset, the driver sends the same unnamed statement as before, so
connection poolers see no change.
- A test double for `Db` must now support `.prepare().execute()` on
these selects. One test double changed.

> 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

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use (shell, file edits, local test and benchmark runs).

## 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
- [x] I have run tests locally and they pass
- [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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-14 20:43:39 -06:00
1 parent ea8c734cb9
commit 8adf0a463a
9 files changed
+368 -26

No files matched your search

@@ -0,0 +1,151 @@
import { randomUUID } from "node:crypto";
import { cpus, loadavg } from "node:os";
import { and, eq, inArray, mapResultRow, sql } from "drizzle-orm";
import { tracer } from "drizzle-orm/tracing";
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { createDb } from "../src/client.js";
import * as schema from "../src/schema/index.js";
import { activityLog, agents, companies, companyMemberships, issues } from "../src/schema/index.js";
import { startEmbeddedPostgresTestDatabase } from "../src/test-embedded-postgres.js";
const iterations = Number(process.env.ITERATIONS ?? 2000);
const passes = Number(process.env.PASSES ?? 5);
const concurrency = Number(process.env.CONCURRENCY ?? 1);
const only = process.env.ONLY?.split(",").filter(Boolean);
const variants = process.env.VARIANTS?.split("|").filter(Boolean);
const median = (values: number[]) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]!;
async function pass(action: () => Promise<unknown> | unknown) {
const cpu = process.cpuUsage(), startedAt = performance.now();
let next = 0;
await Promise.all(Array.from({ length: concurrency }, async () => {
while (next < iterations) { next += 1; await action(); }
}));
const used = process.cpuUsage(cpu);
return { cpu: (used.user + used.system) / iterations, wall: (performance.now() - startedAt) * 1000 / iterations };
}
const results: Record<string, Record<string, { median: number; min: number; max: number }>> = {};
async function measure(statement: string, variant: string, action: () => Promise<unknown> | unknown) {
if (only && !only.includes(statement)) return;
if (variants && !variants.some(name => variant.startsWith(name))) return;
for (let index = 0; index < Math.min(500, iterations); index += 1) await action();
const samples = [];
for (let index = 0; index < passes; index += 1) samples.push(await pass(action));
const cpu = samples.map(sample => sample.cpu);
(results[statement] ??= {})[variant] = { median: Number(median(cpu).toFixed(1)), min: Number(Math.min(...cpu).toFixed(1)),
max: Number(Math.max(...cpu).toFixed(1)) };
console.log(JSON.stringify({ statement, variant, cpuMicros: results[statement][variant],
wallMicros: Number(median(samples.map(sample => sample.wall)).toFixed(1)) }));
}
type Query = { toSQL(): { sql: string; params: unknown[] }; _: { selectedFields?: unknown } };
type Case = {
name: string;
build: (db: ReturnType<typeof createDb>) => Query & PromiseLike<unknown>;
prepare: (db: ReturnType<typeof createDb>) => { execute(values: Record<string, unknown>): Promise<unknown> };
values: Record<string, unknown>;
fields?: (query: Query) => unknown;
};
const database = await startEmbeddedPostgresTestDatabase("paperclip-statement-cpu-");
const db = createDb(database.connectionString, { maxConnections: 4 });
const plainSql = postgres(database.connectionString, { max: 4, onnotice: () => {} });
const plain = drizzle(plainSql, { schema });
try {
const [company] = await db.insert(companies).values({ name: "Bench", issuePrefix: "BEN" }).returning({ id: companies.id });
const companyId = company!.id;
const [agent] = await db.insert(agents).values({ companyId, name: "Agent" }).returning({ id: agents.id });
const issueIds: string[] = [];
for (let index = 0; index < 20; index += 1) {
const [issue] = await db.insert(issues).values({ companyId, title: `Issue ${index}`, assigneeAgentId: agent!.id,
description: "x".repeat(400) }).returning({ id: issues.id });
issueIds.push(issue!.id);
}
const userId = "user-1";
await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId, status: "active",
membershipRole: "owner" });
const listIds = issueIds.slice(0, 10);
const cases: Case[] = [
{
name: "issue parent by id",
build: d => d.select({ parentId: issues.parentId }).from(issues).where(eq(issues.id, issueIds[0]!)),
prepare: d => d.select({ parentId: issues.parentId }).from(issues).where(eq(issues.id, sql.placeholder("id"))).prepare("p1"),
values: { id: issueIds[0] },
},
{
name: "issue row by id",
build: d => d.select().from(issues).where(eq(issues.id, issueIds[1]!)),
prepare: d => d.select().from(issues).where(eq(issues.id, sql.placeholder("id"))).prepare("p2"),
values: { id: issueIds[1] },
},
{
name: "membership by principal",
build: d => d.select({ companyId: companyMemberships.companyId, membershipRole: companyMemberships.membershipRole,
status: companyMemberships.status }).from(companyMemberships).where(and(eq(companyMemberships.companyId, companyId),
eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, userId),
eq(companyMemberships.status, "active"))),
prepare: d => d.select({ companyId: companyMemberships.companyId, membershipRole: companyMemberships.membershipRole,
status: companyMemberships.status }).from(companyMemberships).where(and(
eq(companyMemberships.companyId, sql.placeholder("companyId")), eq(companyMemberships.principalType, "user"),
eq(companyMemberships.principalId, sql.placeholder("userId")), eq(companyMemberships.status, "active"))).prepare("p3"),
values: { companyId, userId },
},
{
name: "join with in-list of 10",
build: d => d.select({ id: issues.id, title: issues.title, status: issues.status, agentName: agents.name })
.from(issues).leftJoin(agents, eq(issues.assigneeAgentId, agents.id))
.where(and(eq(issues.companyId, companyId), inArray(issues.id, listIds))),
prepare: d => d.select({ id: issues.id, title: issues.title, status: issues.status, agentName: agents.name })
.from(issues).leftJoin(agents, eq(issues.assigneeAgentId, agents.id))
.where(and(eq(issues.companyId, sql.placeholder("companyId")), sql`${issues.id} = any(${sql.placeholder("ids")}::uuid[])`)).prepare("p4"),
values: { companyId, ids: listIds },
},
{
name: "update by id",
build: d => d.update(issues).set({ updatedAt: new Date(), checkoutRunId: null }).where(eq(issues.id, issueIds[2]!)) as never,
prepare: d => d.update(issues).set({ updatedAt: sql.placeholder("now") as never, checkoutRunId: null })
.where(eq(issues.id, sql.placeholder("id"))).prepare("p5"),
values: { id: issueIds[2], now: new Date() },
},
{
name: "insert activity",
build: d => d.insert(activityLog).values({ companyId, actorType: "agent", actorId: agent!.id, action: "issue.updated",
entityType: "issue", entityId: issueIds[3]!, agentId: agent!.id, details: { field: "status", from: "todo", to: "done" } }) as never,
prepare: d => d.insert(activityLog).values({ companyId: sql.placeholder("companyId"), actorType: "agent",
actorId: sql.placeholder("actorId"), action: "issue.updated", entityType: "issue", entityId: sql.placeholder("entityId"),
agentId: sql.placeholder("actorId"), details: sql.placeholder("details") }).prepare("p6"),
values: { companyId, actorId: agent!.id, entityId: issueIds[3], details: { field: "status", from: "todo", to: "done" } },
},
];
await measure("tracer", "no-op startActiveSpan (async callback)", () => tracer.startActiveSpan("x", async () => 1));
for (const item of cases) {
const sample = item.build(db);
const { sql: text, params } = sample.toSQL();
const ordered = (sample as unknown as { _prepare(): { fields?: unknown; joinsNotNullableMap?: unknown } })._prepare();
const mapFields = ordered.fields as Parameters<typeof mapResultRow>[0] | undefined;
const joins = ordered.joinsNotNullableMap as Parameters<typeof mapResultRow>[2];
await measure(item.name, "build only (toSQL)", () => item.build(db).toSQL());
await measure(item.name, "drizzle builder, createDb", () => item.build(db));
await measure(item.name, "drizzle builder, plain drizzle()", () => item.build(plain as never));
const prepared = item.prepare(db);
await measure(item.name, "drizzle .prepare() reused", () => prepared.execute(item.values));
if (mapFields) {
await measure(item.name, "unsafe .values() + mapResultRow", async () => {
const rows = await db.$client.unsafe(text, params as never[]).values();
return rows.map(row => mapResultRow(mapFields, row as unknown[], joins));
});
}
await measure(item.name, "unsafe(text, params)", () => db.$client.unsafe(text, params as never[]));
await measure(item.name, "unsafe(text, params, {prepare:true})", () => db.$client.unsafe(text, params as never[], { prepare: true }));
}
console.log(JSON.stringify({ kind: "summary", node: process.version, cpus: cpus().length, loadavg: loadavg(), iterations,
passes, concurrency, results }));
} finally {
await plainSql.end({ timeout: 1 });
await db.$client.end({ timeout: 1 });
await database.cleanup();
}
+2 -2
View File
@@ -6,7 +6,7 @@ import { createRequire } from "node:module";
const { and, eq } = createRequire(new URL("../server/package.json", import.meta.url))("drizzle-orm");
import { agents, companies, createDb, heartbeatRuns, startEmbeddedPostgresTestDatabase, type Db } from "../packages/db/src/index.js";
import { agentRunWritesRevoked } from "../server/src/agent-run-cancellation.js";
import { loadAgentRunAuthentication } from "../server/src/middleware/agent-run-authentication.js";
import { agentRunAuthenticationQuery } from "../server/src/middleware/agent-run-authentication.js";
type Query = { sql: string; params: unknown[] };
const baselineRef = process.argv.find(arg => arg.startsWith("--baseline-ref="))?.slice(15);
@@ -32,7 +32,7 @@ try {
const baseline = new Function("db", "heartbeatRuns", "and", "eq", "claims", `return ${expression}`)(
db, heartbeatRuns, and, eq, { sub: agentId, company_id: companyId, run_id: runId },
).toSQL() as Query;
const treatment = loadAgentRunAuthentication(db, { companyId, agentId, runId }).toSQL();
const treatment = agentRunAuthenticationQuery(db, { companyId, agentId, runId }).toSQL();
function contract(rows: unknown[][]) {
return rows.map(([activeIdentityContextId, responsibleUserId, status, resultJson, contextSnapshot]) => ({
@@ -0,0 +1,47 @@
import { randomBytes, randomUUID } from "node:crypto";
import { loadavg } from "node:os";
process.env.PAPERCLIP_SECRETS_MASTER_KEY ??= randomBytes(32).toString("base64");
process.env.PAPERCLIP_AGENT_JWT_SECRET ??= randomBytes(32).toString("base64");
const { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns, startEmbeddedPostgresTestDatabase } =
await import("../packages/db/src/index.js");
const { createLocalAgentJwt } = await import("../server/src/agent-auth-jwt.js");
const { actorMiddleware } = await import("../server/src/middleware/auth.js");
const N = Number(process.env.N ?? 2000), PASSES = Number(process.env.PASSES ?? 7);
const temporary = await startEmbeddedPostgresTestDatabase("auth-request-cpu-");
const db = createDb(temporary.connectionString);
try {
const [company] = await db.insert(companies).values({ name: "Auth", issuePrefix: "AUT" }).returning();
const [agent] = await db.insert(agents).values({ companyId: company!.id, name: "A", adapterType: "process" }).returning();
const userId = "user-1", runId = randomUUID();
await db.insert(authUsers).values({ id: userId, name: "U", email: "u@example.test", createdAt: new Date(), updatedAt: new Date() });
await db.insert(companyMemberships).values({ companyId: company!.id, principalType: "user", principalId: userId, status: "active", membershipRole: "owner" });
await db.insert(heartbeatRuns).values({ id: runId, companyId: company!.id, agentId: agent!.id, status: "running", responsibleUserId: userId });
const token = createLocalAgentJwt(agent!.id, company!.id, "process", runId, userId)!;
const middleware = actorMiddleware(db, { deploymentMode: "authenticated", resolveSession: async () => null });
const headers: Record<string, string> = { authorization: `Bearer ${token}`, "x-paperclip-run-id": runId };
const once = () => new Promise<void>((resolve, reject) => {
const req: any = { method: "GET", url: "/api/x", originalUrl: "/api/x", path: "/api/x", headers,
header: (name: string) => headers[name.toLowerCase()], get: (name: string) => headers[name.toLowerCase()] };
const res: any = { once() {}, on() {}, status() { return res; }, json(body: unknown) { reject(new Error(JSON.stringify(body))); }, statusCode: 200 };
middleware(req, res, (error?: unknown) => {
if (error) return reject(error);
if (req.actor?.type !== "agent" || req.actor.onBehalfOfMemberships?.length !== 1) return reject(new Error(`bad actor ${JSON.stringify(req.actor)}`));
resolve();
});
});
for (let i = 0; i < 500; i++) await once();
const samples: number[] = [];
for (let p = 0; p < PASSES; p++) {
const c = process.cpuUsage();
for (let i = 0; i < N; i++) await once();
const u = process.cpuUsage(c);
samples.push((u.user + u.system) / N);
}
samples.sort((a, b) => a - b);
console.log(JSON.stringify({ cpuMicrosPerRequest: { median: +samples[Math.floor(PASSES / 2)]!.toFixed(1), min: +samples[0]!.toFixed(1),
max: +samples[PASSES - 1]!.toFixed(1), all: samples.map(s => +s.toFixed(1)) }, loadavg: loadavg().map(v => +v.toFixed(1)) }));
} finally {
await db.$client.end({ timeout: 1 });
await temporary.cleanup();
}
@@ -23,7 +23,9 @@ function createSelectChain(rowsForTable: (table: unknown) => unknown[]) {
from(table: unknown) {
return {
where() {
return Promise.resolve(rowsForTable(table));
return Object.assign(Promise.resolve(rowsForTable(table)), {
prepare: () => ({ execute: async () => rowsForTable(table) }),
});
},
};
},
@@ -0,0 +1,93 @@
import { randomUUID } from "node:crypto";
import express from "express";
import request from "supertest";
import { fillPlaceholders, sql } from "drizzle-orm";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns } from "@paperclipai/db";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
import { createLocalAgentJwt } from "../agent-auth-jwt.js";
import { agentAuthenticationQuery, actorMiddleware, responsibleUserMembershipsQuery } from "../middleware/auth.js";
import { agentRunAuthenticationQuery } from "../middleware/agent-run-authentication.js";
const support = await getEmbeddedPostgresTestSupport();
(support.supported ? describe : describe.skip)("agent request authentication statements", () => {
let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
let db: ReturnType<typeof createDb>;
const companyId = randomUUID(), agentId = randomUUID(), runId = randomUUID(), userId = `user-${randomUUID()}`;
beforeAll(async () => {
vi.stubEnv("PAPERCLIP_AGENT_JWT_SECRET", "agent-auth-prepared-statements-secret");
database = await startEmbeddedPostgresTestDatabase("paperclip-agent-auth-prepared-");
db = createDb(database.connectionString);
await db.insert(companies).values({ id: companyId, name: "Prepared authentication", issuePrefix: "PREP" });
await db.insert(authUsers).values({ id: userId, name: "Owner", email: "owner@example.test", emailVerified: true,
createdAt: new Date(), updatedAt: new Date() });
await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: userId,
status: "active", membershipRole: "owner" });
await db.insert(agents).values({ id: agentId, companyId, name: "Worker", adapterType: "process", lifecycleHolds: [] });
await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, status: "running", responsibleUserId: userId,
resultJson: { executionCancellation: { state: "none" }, freshContinuationSupersededAt: null },
contextSnapshot: { conversationMode: true, issueId: randomUUID() } });
}, 30_000);
afterAll(async () => {
vi.unstubAllEnvs();
await db?.$client.end({ timeout: 5 });
await database?.cleanup();
}, 60_000);
const cases = () => [
{
bound: agentAuthenticationQuery(db, agentId),
prepared: agentAuthenticationQuery(db, sql.placeholder("agentId")),
values: { agentId },
},
{
bound: agentRunAuthenticationQuery(db, { runId, companyId, agentId }),
prepared: agentRunAuthenticationQuery(db, { runId: sql.placeholder("runId"), companyId: sql.placeholder("companyId"),
agentId: sql.placeholder("agentId") }),
values: { runId, companyId, agentId },
},
{
bound: responsibleUserMembershipsQuery(db, { companyId, userId }),
prepared: responsibleUserMembershipsQuery(db, { companyId: sql.placeholder("companyId"), userId: sql.placeholder("userId") }),
values: { companyId, userId },
},
];
it("sends the same statement and returns the same rows as the query builder", async () => {
for (const { bound, prepared, values } of cases()) {
const statement = prepared.prepare("fixture");
const built = bound.toSQL(), placeholders = prepared.toSQL();
expect(placeholders.sql).toBe(built.sql);
expect(fillPlaceholders(statement.getQuery().params, values)).toEqual(built.params);
const rows = await bound;
expect(rows).toHaveLength(1);
expect(await statement.execute(values)).toStrictEqual(rows);
}
});
it("builds the request authentication statements once per database client", async () => {
const app = express();
app.use(actorMiddleware(db, { deploymentMode: "authenticated", resolveSession: async () => null }));
app.get("/actor", (req, res) => { res.json(req.actor); });
const token = createLocalAgentJwt(agentId, companyId, "process", runId, userId)!;
const call = () => request(app).get("/actor").set("authorization", `Bearer ${token}`).set("x-paperclip-run-id", runId);
const select = vi.spyOn(db, "select");
const first = await call();
expect(first.status).toBe(200);
expect(first.body).toMatchObject({ type: "agent", agentId, companyId, runId, onBehalfOfUserId: userId,
onBehalfOfMemberships: [{ companyId, membershipRole: "owner", status: "active" }] });
select.mockClear();
for (let index = 0; index < 3; index += 1) {
const next = await call();
expect(next.status).toBe(200);
expect(next.body).toEqual(first.body);
}
expect(select).not.toHaveBeenCalled();
select.mockRestore();
});
});
@@ -2,7 +2,7 @@ import { eq, fillPlaceholders, sql } from "drizzle-orm";
import { PgDialect, pgTable, timestamp, uuid } from "drizzle-orm/pg-core";
import { describe, expect, it, vi } from "vitest";
import type { Db } from "@paperclipai/db";
import { columnPlaceholder, preparedStatements } from "../services/prepared-statements.js";
import { columnPlaceholder, preparedStatement, preparedStatements } from "../services/prepared-statements.js";
describe("prepared statements", () => {
it("prepares a shape one time for a client, and again for another client or shape", () => {
@@ -18,6 +18,17 @@ describe("prepared statements", () => {
expect(prepare.mock.calls).toEqual([[root, "first"], [root, "after"], [transaction, "first"]]);
});
it("prepares a single statement one time for each client", () => {
const prepare = vi.fn((db: Db) => ({ db }));
const statement = preparedStatement(prepare);
const root = {} as Db, other = {} as Db;
const first = statement(root);
expect(statement(root)).toBe(first);
expect(statement(other)).toEqual({ db: other });
expect(statement(other)).not.toBe(first);
expect(prepare.mock.calls).toEqual([[root], [other]]);
});
it("encodes a placeholder value with the column, as the query builder encodes a bound value", () => {
const table = pgTable("prepared_statement_fixture", { id: uuid("id"), at: timestamp("at", { withTimezone: true }) });
const at = new Date("2026-11-12T10:00:00.123Z");
@@ -1,12 +1,12 @@
import { and, eq, sql } from "drizzle-orm";
import { and, eq, sql, type Placeholder } from "drizzle-orm";
import { heartbeatRuns, type Db } from "@paperclipai/db";
import { requestRunIdentityFields } from "../services/run-identity.js";
import { preparedStatement } from "../services/prepared-statements.js";
export function loadAgentRunAuthentication(db: Db, input: {
runId: string;
companyId: string;
agentId: string;
}) {
type Bound<Value> = Value | Placeholder;
export type AgentRunAuthenticationBinding = { runId: Bound<string>; companyId: Bound<string>; agentId: Bound<string> };
export function agentRunAuthenticationQuery(db: Db, input: AgentRunAuthenticationBinding) {
return db.select({
activeIdentityContextId: heartbeatRuns.activeIdentityContextId,
responsibleUserId: heartbeatRuns.responsibleUserId,
@@ -27,3 +27,17 @@ export function loadAgentRunAuthentication(db: Db, input: {
eq(heartbeatRuns.agentId, input.agentId),
));
}
const agentRunAuthenticationStatement = preparedStatement(db => agentRunAuthenticationQuery(db, {
runId: sql.placeholder("runId"),
companyId: sql.placeholder("companyId"),
agentId: sql.placeholder("agentId"),
}).prepare("agent_run_authentication"));
export function loadAgentRunAuthentication(db: Db, input: {
runId: string;
companyId: string;
agentId: string;
}) {
return agentRunAuthenticationStatement(db).execute(input);
}
+31 -16
View File
@@ -2,7 +2,7 @@ import { notifyMuseContactVerification } from "../modules/external-agents/index.
import { idleApiActivity } from "../services/idle-api-activity.js";
import { createHash, timingSafeEqual } from "node:crypto";
import type { Request, RequestHandler } from "express";
import { and, eq, exists, isNull, sql } from "drizzle-orm";
import { and, eq, exists, isNull, sql, type Placeholder } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import {
activityLog,
@@ -31,6 +31,7 @@ import { logger } from "./logger.js";
import { localAgentProcessBoundary, type LocalAgentProcessBoundary } from "./local-agent-process-boundary.js";
import { resolveRequestRunIdentity } from "../services/run-identity.js";
import { boardAuthService } from "../services/board-auth.js";
import { preparedStatement } from "../services/prepared-statements.js";
import { retryIdempotentDatabaseOperation } from "../database-retry.js";
import { beginIdleTrackedWork } from "../services/task-admission.js";
import { notifyChatCompanyAuthorityChange } from "../services/chat-run-milestone-notifications.js";
@@ -76,11 +77,20 @@ const agentAuthenticationFields = {
lifecycleHolds: agents.lifecycleHolds,
};
async function loadResponsibleUserMemberships(
db: Db,
input: { companyId: string; userId: string | null },
) {
if (!input.userId) return [];
type Bound<Value> = Value | Placeholder;
export function agentAuthenticationQuery(db: Db, agentId: Bound<string>) {
return db.select(agentAuthenticationFields).from(agents).where(eq(agents.id, agentId));
}
const agentAuthenticationStatement = preparedStatement(db =>
agentAuthenticationQuery(db, sql.placeholder("agentId")).prepare("agent_authentication"));
function loadAgentAuthentication(db: Db, agentId: string) {
return agentAuthenticationStatement(db).execute({ agentId }).then((rows) => rows[0] ?? null);
}
export function responsibleUserMembershipsQuery(db: Db, input: { companyId: Bound<string>; userId: Bound<string> }) {
return db
.select({
companyId: companyMemberships.companyId,
@@ -99,6 +109,19 @@ async function loadResponsibleUserMemberships(
);
}
const responsibleUserMembershipsStatement = preparedStatement(db => responsibleUserMembershipsQuery(db, {
companyId: sql.placeholder("companyId"),
userId: sql.placeholder("userId"),
}).prepare("responsible_user_memberships"));
async function loadResponsibleUserMemberships(
db: Db,
input: { companyId: string; userId: string | null },
) {
if (!input.userId) return [];
return responsibleUserMembershipsStatement(db).execute({ companyId: input.companyId, userId: input.userId });
}
/**
* The user's own active company memberships — the exact company scope a
* locally authenticated session actor carries. Shared by the session path
@@ -357,11 +380,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa
return;
}
const agentRecord = await db
.select(agentAuthenticationFields)
.from(agents)
.where(eq(agents.id, claims.sub))
.then((rows) => rows[0] ?? null);
const agentRecord = await loadAgentAuthentication(db, claims.sub);
if (!agentRecord || agentRecord.companyId !== claims.company_id) {
next(unauthorized("Agent record is missing or belongs to another company; obtain fresh credentials and retry"));
@@ -478,11 +497,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHa
.set({ lastUsedAt: new Date() })
.where(eq(agentApiKeys.id, key.id));
const agentRecord = await db
.select(agentAuthenticationFields)
.from(agents)
.where(eq(agents.id, key.agentId))
.then((rows) => rows[0] ?? null);
const agentRecord = await loadAgentAuthentication(db, key.agentId);
if (!agentRecord || agentRecord.companyId !== key.companyId) {
next(unauthorized("Agent record is missing or belongs to another company; obtain fresh credentials and retry"));
@@ -12,6 +12,15 @@ export function preparedStatements<Shape extends string, Statement>(prepare: (db
};
}
export function preparedStatement<Statement>(prepare: (db: Db) => Statement) {
const statements = new WeakMap<Db, Statement>();
return (db: Db): Statement => {
let statement = statements.get(db);
if (!statement) statements.set(db, statement = prepare(db));
return statement;
};
}
export function columnPlaceholder(name: string, column: DriverValueEncoder<unknown, unknown>): Param {
return new Param(sql.placeholder(name), column);
}