# `tenant-cap`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

The `tenant-cap` module owns the per-tenant SSE connection counter the
engine consults during handshake. A tenant that has already reached
`maxConnectionsPerTenant` open connections receives `429 Too Many
Requests` with `SSE_BUN.TENANT_CAP_EXCEEDED` — the engine never opens
the long-lived stream, so the per-tenant ceiling is enforced exactly
at the handshake boundary and never as a mid-stream race.

## Features

- O(1) `tryAcquire` / `release` keyed by `TenantId`.
- `count(tenantId)` exposed so OTel gauges can sample without exposing
  the internal map.
- `total` aggregate count for global capacity dashboards.
- Tight error context: `tenantId`, `limit`, `current` attached to every
  thrown `SseBunError` so operators do not need to grep request logs.
- Idempotent `release` — releasing an unknown tenant does nothing.

## Usage: Basic

```ts
import { createTenantConnectionCap } from "@suaveplan/api-sse-bun";

const cap = createTenantConnectionCap(1000);
cap.tryAcquire("acme" as never);
console.log(cap.count("acme" as never)); // 1
cap.release("acme" as never);
```

## Usage: Advanced

```ts
import {
    createTenantConnectionCap,
    SSE_BUN_CODES,
    SseBunError,
} from "@suaveplan/api-sse-bun";

const cap = createTenantConnectionCap(2);
const tenant = "acme" as never;
cap.tryAcquire(tenant);
cap.tryAcquire(tenant);
try {
    cap.tryAcquire(tenant);
} catch (err) {
    if (
        err instanceof SseBunError &&
        err.code === SSE_BUN_CODES.TENANT_CAP_EXCEEDED
    ) {
        // return 429 ...
    }
}
```

## API Reference

- `interface TenantConnectionCap` — `tryAcquire(tenantId)`,
  `release(tenantId)`, `count(tenantId)`, `total`.
- `function createTenantConnectionCap(max): TenantConnectionCap`.

## Implementation Notes

The cap uses a `Map<TenantId, number>` keyed by the branded tenant id;
the brand prevents an unsanitised header value from accidentally being
treated as a tenant key. `release` decrements when the count is `> 1`
and deletes the entry on the last release so the map's footprint
matches the live connection set. `total` is a running counter rather
than a derived sum so reading it from the OTel callback is O(1).