Optimize performance

Measure before you change anything

Three tools report where time goes. Spans time each unit of work, the metrics collector aggregates them, and an instrumented store times each storage call.

import { betterIam } from 'better-iam';
import { instrumentStore } from 'better-iam/core';
import { postgresAdapter } from 'better-iam/adapter-postgres';

const database = instrumentStore(
  postgresAdapter({ connectionString: process.env.DATABASE_URL! }),
  (call) => {
    // call: { method, collection, filterKeys, page, records, durationMs, inTransaction, failed }
    if (call.durationMs > 50) console.warn('slow IAM storage call', call);
  },
);

export const iam = betterIam({
  database,
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: 'https://identity.example.com',
  observability: {
    // Prometheus counters and histograms, scraped at GET /api/iam/metrics.
    metrics: { bearerToken: process.env.METRICS_TOKEN },
    onSpan(span) {
      // kind: 'operation' | 'authorize' | 'authorizeMany' | 'listAccessible' | 'auth' | 'http'
      if (span.durationMs > 250) console.warn('slow IAM span', span.kind, span.name, span.durationMs);
    },
  },
});

• better_iam_span_duration_seconds is a histogram by kind, and better_iam_spans_total counts spans by kind, name, outcome, and code. See Prometheus metrics.
• instrumentStore reports filter keys, never values, so its output is safe to log. It reports a keyset cursor as page.keyset: true. See Measuring.
• In the repository, pnpm bench:scale seeds BENCH_IDENTITIES identities (default 5000) and prints per-operation latency and storage calls over BENCH_ITERATIONS runs (default 40).

Many storage calls per span usually means a loop that one batch call can replace (step 3). A few slow calls usually means a missing migration, a stale PostgreSQL index, or a table the retention jobs should have trimmed (step 2).

Keep storage on its indexes and its tables small

The indexes come from migrations, and the retention jobs keep the indexed tables from growing with traffic.

• Apply every migration. Lookup indexes ship as schema steps (0002_query_indexes through 0006_protection_indexes). better-iam doctor reports schema-behind when one is missing. See Migrations.
• Vacuum after bulk imports on PostgreSQL. Rows written after the GIN index exists wait in its pending list until a vacuum merges them. After an import or a store-import, run VACUUM ANALYZE iam_records.
• Run purge and sweep. Expired sessions, OAuth and SAML artifacts, and delivered outbox rows stay in their collections until the sweep deletes them, and dispatchOutbox reads the whole outbox. See Retention sweep.
• Keep transactions short in your own code. Never make network calls inside iam.store.transaction() or a plugin transaction: other IAM transactions wait for the lock meanwhile.
• Know the libSQL write cost. @libsql/client compiles each statement on every call, so local libSQL writes cost more than the SQLite adapter's, which caches prepared statements.

better-iam migrate --config better-iam.config.mjs
psql "$DATABASE_URL" -c 'VACUUM ANALYZE iam_records'
better-iam sweep --config better-iam.config.mjs

Batch authorization checks

Each iam.authorize call is its own transaction, so ten checks wait for the lock ten times. Batch calls prepare the caller's state once and answer everything in one transaction.

import { iam } from '@/lib/iam';

export async function toolbarActions(headers: Headers, tenantId: string, documentId: string) {
  const resource = { type: 'document', id: documentId };
  // One transaction, one consistent view of the configuration, up to 50 checks.
  const { results } = await iam.authorizeMany({
    headers,
    tenantId,
    checks: [
      { action: 'documents:write', resource },
      { action: 'documents:share', resource },
      { action: 'documents:delete', resource },
    ],
  });
  return Object.fromEntries(results.map((result) => [result.action, result.allowed]));
}

listAccessible loads the caller's grants and boundaries once and evaluates every registration of the type against them, so its cost does not multiply by the number of grants. Batch results are advisory: still call iam.require immediately before the protected operation. See Batches and reverse queries.

Route: POST /resources/registerMany

Filter lists in your own database

For a list page over your own table, ask for a query plan once and let your database do the filtering, sorting, and paging.

import { filterToSql } from 'better-iam/core';
import { iam } from '@/lib/iam';
import { db } from '@/lib/db';

const columns: Record<string, string> = { id: 'd.id', ownerId: 'd.owner_id' };

export async function readableDocuments(headers: Headers, tenantId: string) {
  const plan = await iam.planResources({ headers, tenantId, action: 'documents:read', type: 'document' });
  if (plan.kind === 'never') return [];
  const where = filterToSql(plan.filter, {
    dialect: 'postgres',
    column: (field) => columns[field],
    offset: 1, // $1 is the tenant
  });
  return db.query(`SELECT * FROM documents d WHERE d.tenant_id = $1 AND ${where.sql} LIMIT 50`, [
    tenantId,
    ...where.params,
  ]);
}

planResources needs no permission, is not audited, and runs once per page instead of once per row. A filter a target cannot express refuses with UNSUPPORTED_FILTER; then fall back to authorizeMany over candidate rows. See Data filtering.

Route: POST /filters/plan

Verify callers downstream without calling IAM

Services behind your application do not need to ask IAM who is calling on every request. Two token types are signed by IAM and verified offline:

import { verifyAssertion } from 'better-iam';

// Holds only the derived key, never the deployment secret.
export function caller(token: string) {
  return verifyAssertion(token, { key: process.env.IAM_ASSERTION_KEY!, audience: 'reports' });
}

The trade-off is revocation: a verified token stays valid until it expires, so keep lifetimes short. Use this for reads that tolerate that window, and keep iam.require for mutations. See stateless assertions and Session tokens.

Route: POST /assertions/issue

Keep slow work off the request path

Nothing in a request waits on a mail provider, a webhook endpoint, or a cleanup pass. Make sure the jobs that do that work run often enough and in the right process.

• Deliveries and event subscribers run only when iam.auth.dispatchOutbox() and iam.events.dispatch() run. dispatchOutbox(limit?) sends up to limit messages per call (default 100, at most 1000), each claimed in its own short transaction, so several workers never send the same message.
• The retention sweep and audit archiving run in short batches (sweepExpired uses batchSize, 500 by default), so each holds the lock briefly.
• With accessUsage, counts are written in the background; call iam.flushAccessUsage() before shutdown.

import { iam } from './lib/iam';

setInterval(async () => {
  await iam.auth.dispatchOutbox(500);
  await iam.events.dispatch();
}, 60_000);

process.on('SIGTERM', async () => {
  await iam.flushAccessUsage();
  process.exit(0);
});

See Scheduled jobs for every job and its cadence.

Page large reads

Read big result sets in pages whose cost does not grow with depth.

• audit.export follows the chain by sequence: start at fromSequence, follow nextSequence, up to 10000 events per page.
• audit.list takes from and to (epoch milliseconds). Narrow by time instead of using a deep offset.
• List methods such as identities.list and listAccessible take limit and offset.
• In plugin or adapter code, store.find(collection, filter, { after, limit }) pages by record ID (keyset), and findOrdered(store, collection, filter, order) from better-iam/core pages by a numeric field in SQL.

import { appendFile } from 'node:fs/promises';
import { iam } from '../lib/iam';

export async function exportAudit(credential: { token: string }, tenantId: string, file: string) {
  let fromSequence: number | undefined = 1;
  while (fromSequence !== undefined) {
    const page = await iam.api.audit.export(credential, { tenantId, fromSequence, limit: 5000 });
    if (page.count) await appendFile(file, `${page.body}\n`);
    fromSequence = page.nextSequence;
  }
}

Route: POST /audit/export

Tune the adapter

The adapter options decide how long a transaction waits for the lock before it fails with STORAGE_BUSY (503).

import { postgresAdapter } from 'better-iam/adapter-postgres';

export const database = postgresAdapter({
  connectionString: process.env.DATABASE_URL!,
  poolSize: 10, // default 10
  lockTimeoutMs: 5000, // default 5000: the wait for the IAM lock
});

Put the database close to the application: every transaction holds the lock for at least its round trips. On SQLite, durability: 'normal' in WAL mode makes commits cheaper but can lose the last commits on power loss (never the database); keep 'full' unless you accept that.