perf(server): skip the per-request stale instance-admin purge when no row exists (#21680)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Cloud-hosted instances authenticate each request through trusted
Cloud headers in the actor middleware
> - That path deletes stale `instance_admin` rows for the user on every
request, static files and live-events upgrades included
> - On an idle hosted instance this delete ran about 1.2 times a second,
which is a write on an instance-wide table for each request
> - Almost always there is no row to delete, so the statement is wasted
work and a database round trip
> - This pull request finds out if a stale row exists inside the
membership read that the request already does, and deletes only when a
row exists
> - The benefit is one read and no write for each unchanged
authenticated request, with the same purge on the very next request when
a stale row appears

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Cloud trusted-header authentication in the actor middleware.

**Subsystem affected**
Server authentication (`server/src/middleware/auth.ts`).

**Current behavior**
`resolveCloudTenantActor` in `server/src/middleware/auth.ts` sends
`delete from instance_user_roles where user_id = $1 and role =
'instance_admin'` for every trusted-header request. The actor middleware
runs before the static UI, so asset requests run it too. Each
live-events WebSocket upgrade runs it again through `resolveCloudActor`.
The retry wrapper runs it again after a transient connection error.

**Proposed behavior**
An unchanged request sends no write. A stale `instance_admin` row is
still removed on the next request after it appears.

**Reason and benefit**
Idle hosted instances send about one delete for each request. This costs
a round trip and a write statement on the main database for no change.

**Breaking changes**
None. The resolved actor and the authorization decisions do not change.

## What Changed

- The Cloud trusted-header path reads the user's active memberships
together with an `exists` check for an `instance_admin` row, in one
statement.
- The purge runs only when that check finds a row, when the user has no
active membership row yet (first request), or when the read fails.
- The session path and the Cloud path share one membership filter
function, so both still resolve the same access set.
- New test `server/src/__tests__/cloud-tenant-actor-statements.test.ts`
meters the statements of one authenticated request on the embedded test
database.

## Verification

- `cd server && npx vitest run
src/__tests__/cloud-tenant-actor-statements.test.ts
src/middleware/cloud-tenant-actor.test.ts
src/__tests__/cloud-tenant-actor-round-trips.test.ts`: 41 passed.
- Red/green: with the `origin/master` version of `auth.ts`, the new test
fails. An unchanged member request sends 2 statements, and one of them
is the delete. With this change it sends 1 read and 0 writes.
- The test inserts a stale `instance_admin` row between two requests.
The next request deletes it, and the request after that sends no write
again.
- The test changes the stack role from member to admin and back. The
membership role and the experimental-settings access change on the very
next request each time.

## Risks

- Low risk. The actor that the middleware returns is the same.
Authorization decisions do not change.
- The purge now runs after the membership read, not before the tenant
sync. The sync does not touch `instance_user_roles`, so the order does
not matter. The request still waits for the purge before it continues.
- A race between the read and a new row insert existed before too
(delete, then insert). The next request removes such a row.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in Claude Code.

## 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 18:34:30 -06:00
1 parent dcba9628c7
commit cf2a4221e3
2 files changed
+158 -17

No files matched your search

@@ -0,0 +1,116 @@
import { resolveExternalTestDatabaseUrl } from "./helpers/external-test-database.js";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { and, eq } from "drizzle-orm";
import {
activityLog,
authUsers,
companies,
companyMemberships,
createDb,
instanceUserRoles,
principalPermissionGrants,
} from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import { meterDatabaseStatements } from "./helpers/database-statement-meter.js";
import { cloudActorHeaderSourceFromHeaders, resolveCloudTenantActor } from "../middleware/auth.js";
const external = resolveExternalTestDatabaseUrl("PAPERCLIP_CLOUD_PROVISIONING_TEST_DATABASE_URL");
const embeddedPostgresSupport = external ? { supported: true, reason: undefined } : await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
const SERVER_TOKEN = "test-server-token";
function tenantHeaders(userId: string, stackRole: string) {
return cloudActorHeaderSourceFromHeaders({
"x-paperclip-cloud-tenant-token": SERVER_TOKEN,
"x-paperclip-cloud-user-id": userId,
"x-paperclip-cloud-user-email": `${userId}@example.com`,
"x-paperclip-cloud-stack-id": `stack-${userId}`,
"x-paperclip-cloud-stack-role": stackRole,
});
}
const writes = (statements: { sql: string }[]) =>
statements.filter((entry) => /^\s*(delete|insert|update)\b/i.test(entry.sql)).map((entry) => entry.sql);
describeEmbeddedPostgres("cloud tenant actor statements per request", () => {
let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
let db!: ReturnType<typeof createDb>;
let meter!: ReturnType<typeof meterDatabaseStatements>;
beforeAll(async () => {
if (!external) tempDb = await startEmbeddedPostgresTestDatabase("paperclip-tenant-statements-");
const url = external ?? tempDb!.connectionString;
db = createDb(url);
meter = meterDatabaseStatements(db, url);
process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN = SERVER_TOKEN;
}, 30_000);
afterAll(async () => {
delete process.env.PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN;
meter?.uninstall();
await db?.delete(activityLog);
await db?.delete(principalPermissionGrants);
await db?.delete(companyMemberships);
await db?.delete(companies);
await db?.delete(instanceUserRoles);
await db?.delete(authUsers);
await db?.$client.end({ timeout: 1 });
await tempDb?.cleanup();
});
async function resolveMetered(userId: string, stackRole: string) {
const before = meter.read();
meter.startLog();
const actor = await resolveCloudTenantActor(db, tenantHeaders(userId, stackRole));
const statements = meter.stopLog();
return { actor, statements, count: meter.read().statements - before.statements };
}
async function staleAdminRows(userId: string) {
return db.select({ id: instanceUserRoles.id }).from(instanceUserRoles)
.where(and(eq(instanceUserRoles.userId, userId), eq(instanceUserRoles.role, "instance_admin")));
}
it("sends one read and no write for an unchanged authenticated request", async () => {
await resolveCloudTenantActor(db, tenantHeaders("user-steady", "member"));
const { actor, statements, count } = await resolveMetered("user-steady", "member");
expect(actor).toMatchObject({ type: "board", userId: "user-steady", isInstanceAdmin: false });
expect(writes(statements)).toEqual([]);
expect(count).toBe(1);
});
it("purges a stale instance_admin row on the very next request", async () => {
await resolveCloudTenantActor(db, tenantHeaders("user-stale", "member"));
await db.insert(instanceUserRoles).values({ userId: "user-stale", role: "instance_admin" });
expect(await staleAdminRows("user-stale")).toHaveLength(1);
const { actor, statements } = await resolveMetered("user-stale", "member");
expect(actor).toMatchObject({ isInstanceAdmin: false });
expect(writes(statements)).toEqual([expect.stringMatching(/^delete from "instance_user_roles"/)]);
expect(await staleAdminRows("user-stale")).toHaveLength(0);
const next = await resolveMetered("user-stale", "member");
expect(writes(next.statements)).toEqual([]);
});
it("applies a stack role added or removed in the header on the very next request", async () => {
const member = await resolveMetered("user-roles", "member");
expect(member.actor?.memberships?.[0]?.membershipRole).toBe("member");
expect(member.actor?.canManageExperimentalSettings).toBe(false);
const admin = await resolveMetered("user-roles", "admin");
expect(admin.actor?.memberships?.[0]?.membershipRole).toBe("owner");
expect(admin.actor?.canManageExperimentalSettings).toBe(true);
const demoted = await resolveMetered("user-roles", "member");
expect(demoted.actor?.memberships?.[0]?.membershipRole).toBe("member");
expect(demoted.actor?.canManageExperimentalSettings).toBe(false);
const [stored] = await db.select({ membershipRole: companyMemberships.membershipRole }).from(companyMemberships)
.where(and(eq(companyMemberships.principalType, "user"), eq(companyMemberships.principalId, "user-roles")));
expect(stored?.membershipRole).toBe("member");
});
});
+42 -17
View File
@@ -104,6 +104,14 @@ async function loadResponsibleUserMemberships(
* locally authenticated session actor carries. Shared by the session path
* and the Cloud trusted-header path so both resolve the same access set.
*/
function activeUserMembershipFilter(userId: string) {
return and(
eq(companyMemberships.principalType, "user"),
eq(companyMemberships.principalId, userId),
eq(companyMemberships.status, "active"),
);
}
async function loadActiveUserCompanyMemberships(db: Db, userId: string) {
return db
.select({
@@ -112,13 +120,20 @@ async function loadActiveUserCompanyMemberships(db: Db, userId: string) {
status: companyMemberships.status,
})
.from(companyMemberships)
.where(
and(
eq(companyMemberships.principalType, "user"),
eq(companyMemberships.principalId, userId),
eq(companyMemberships.status, "active"),
),
);
.where(activeUserMembershipFilter(userId));
}
async function loadCloudTenantMembershipsWithStaleAdmin(db: Db, userId: string) {
return db
.select({
companyId: companyMemberships.companyId,
membershipRole: companyMemberships.membershipRole,
status: companyMemberships.status,
staleInstanceAdmin: sql<boolean>`exists (select 1 from ${instanceUserRoles}
where ${instanceUserRoles.userId} = ${userId} and ${instanceUserRoles.role} = 'instance_admin')`,
})
.from(companyMemberships)
.where(activeUserMembershipFilter(userId));
}
async function auditAgentJwtRunHeaderMismatch(
@@ -612,15 +627,21 @@ async function resolveCloudTenantActorOnce(
// service's own instanceUserRoles lookup — so actively purge them on every
// trusted-header authentication instead of merely no longer inserting them.
//
// Every request runs this path, static files included. The purge and the
// tenant sync stay ordered; the two reads below are independent of them, so
// they run concurrently. A loaded database then costs one round trip per
// request rather than three in a row.
const purgeAndSync = (async () => {
// Every request runs this path, static files included. The membership read
// below reports whether such a row exists, so the purge runs only when one
// does, or when that read cannot tell. A loaded database then costs one
// round trip per request rather than three in a row.
const membershipRowsRead = loadCloudTenantMembershipsWithStaleAdmin(db, userId);
const purgeStaleInstanceAdmin = async () => {
await db
.delete(instanceUserRoles)
.where(and(eq(instanceUserRoles.userId, userId), eq(instanceUserRoles.role, "instance_admin")));
};
const purge = membershipRowsRead.then(
(rows) => rows.length === 0 || rows.some((row) => row.staleInstanceAdmin) ? purgeStaleInstanceAdmin() : undefined,
() => purgeStaleInstanceAdmin(),
);
const tenantSync = (async () => {
await syncCloudTenantWrites(db, userId, syncFingerprint, async () => {
const now = new Date();
await db
@@ -708,8 +729,10 @@ async function resolveCloudTenantActorOnce(
// blocking authentication, mirroring the fail-closed owner-elevation
// resolution below.
const additionalMembershipsRead: Promise<{ companyId: string; membershipRole: string | null; status: string }[]> =
loadActiveUserCompanyMemberships(db, userId).then(
(rows) => rows.filter((row) => row.companyId !== companyId),
membershipRowsRead.then(
(rows) => rows
.filter((row) => row.companyId !== companyId)
.map((row) => ({ companyId: row.companyId, membershipRole: row.membershipRole, status: row.status })),
(err) => {
logger.warn(
{ err, userId, stackId },
@@ -728,11 +751,13 @@ async function resolveCloudTenantActorOnce(
// Settle every started statement before an error leaves: the caller stops
// counting authentication work for idle and drain checks when this throws,
// and the owner-settings read can insert the missing settings row.
const [synced, membershipsRead, ownerRead] = await Promise.allSettled([
purgeAndSync,
const [purged, synced, membershipsRead, ownerRead] = await Promise.allSettled([
purge,
tenantSync,
additionalMembershipsRead,
ownerInstanceAdminRead,
]);
if (purged.status === "rejected") throw purged.reason;
if (synced.status === "rejected") throw synced.reason;
if (membershipsRead.status === "rejected") throw membershipsRead.reason;
if (ownerRead.status === "rejected") throw ownerRead.reason;