@pipeline-builder/api-core 5.2.3 → 5.2.4

package/lib/services/quota.d.ts

@@ -1,6 +1,107 @@
-import type { Response } from 'express';
-import type { QuotaType, QuotaCheckResult } from '../types/common.js';
+import type { Request, Response } from 'express';
+import { type MeteredIncrementGroup } from './quota-increment-batcher.js';
+import type { PrincipalType, QuotaType, QuotaCheckResult } from '../types/common.js';
+import { ErrorCode } from '../types/error-codes.js';
 import { type QuotaTier } from '../types/quota-tiers.js';
+/**
+ * Budget for one `check` of a COUNTER quota (`QUOTA_CHECK_TIMEOUT_MS`, default
+ * 300), with no retry.
+ *
+ * The check is a read gate that FAILS OPEN, run ahead of the request it gates:
+ * the old 5 s timeout × 2 attempts meant a slow quota service added up to 10 s
+ * to every metered request and then let it through anyway. A short budget turns
+ * the same incident into a ≤ 300 ms fail-open (counted on
+ * `quota_fail_open_total`, which alerts) — and with the per-pod check cache in
+ * front (api-server `checkQuota`) a healthy service is asked at most once per
+ * org/type per cache TTL.
+ *
+ * `storageBytes` keeps the client timeout and one retry: it is a MEASURED read
+ * (the quota service walks the org's registry namespace on a cold cache) behind
+ * the registry's fail-CLOSED push gate, where a premature timeout refuses a push.
+ */
+export declare const QUOTA_CHECK_TIMEOUT_MS: number;
+/** Who / what spent (or got back) a quota unit. All fields optional. */
+export interface QuotaUsageAttribution {
+    principalType?: PrincipalType;
+    /** The user id or service-account id behind the call (the token's `sub`). */
+    principalId?: string;
+    /** The revocable credential: the access key the token derives from, else its `jti`. */
+    keyId?: string;
+    /** `METHOD /route/:pattern` — the matched route PATTERN, never the raw URL (no ids, no query). */
+    route?: string;
+    /** The pipeline the call was made for (`:pipelineId` param or `X-Pipeline-Id` header). */
+    pipelineId?: string;
+    requestId?: string;
+    /**
+     * AI calls only: which product surface spent the unit — `ask`, `agent`,
+     * `agent-tool:<name>`, `pipeline-generate`, `plugin-generate`,
+     * `report-summary`. Set by api-server's `withAiCallReservation`.
+     */
+    feature?: string;
+    /** AI calls only: the model id the reservation was resolved to (never a key). */
+    model?: string;
+    /** AI calls only: whose key served the call — `platform`, `org` or `request` (BYOK). */
+    keySource?: AiKeySource;
+}
+/** Whose key serves an AI call (mirrors ai-core `KeySource`). Only `platform` spends `aiCalls`. */
+export type AiKeySource = 'platform' | 'org' | 'request';
+/** Token counts an AI call reports after it settles (see {@link QuotaService.reportUsage}). */
+export interface QuotaTokenUsage {
+    tokensIn: number;
+    tokensOut: number;
+}
+/**
+ * Attribution for the request being served: the verified principal, the matched
+ * route pattern, the pipeline (`:pipelineId` param or a sanitized
+ * `X-Pipeline-Id` header) and the request id. Read off `req` directly rather than
+ * the ambient audit context because the metering middleware runs in a `finish`
+ * listener, where the request's async scope is no longer guaranteed.
+ */
+export declare function quotaAttributionFromRequest(req: Request): QuotaUsageAttribution;
+/**
+ * The quota type a metered request actually spends.
+ *
+ * `apiCalls` is the PEOPLE's budget — an interactive session. A request made by
+ * a NON-INTERACTIVE credential spends `automationCalls` instead, never both, so
+ * a fleet of self-mutating pipelines can't exhaust the console for the humans
+ * in the same org:
+ *  - an org SERVICE ACCOUNT (`principalType: 'service_account'` —
+ *    platform-automation, pipeline-register, reporting-ingest, registry-push);
+ *  - a PERSONAL ACCESS KEY: the exchanged key token (`token_use: 'api_key'`)
+ *    and anything minted while holding one (`parentKeyId`). A PAT in a CI job
+ *    is automation whoever owns it — billing it as a person let one script
+ *    lock its owner's teammates out of the console. CI should still use a
+ *    service-account key (it survives the person leaving); either way the
+ *    traffic now lands on `automationCalls`.
+ * Every other type is returned unchanged: an AI call or a pipeline creation
+ * costs the same whoever makes it.
+ *
+ * `meterQuotaOnSuccess` and `checkQuota` call this themselves, so a service
+ * mounts both with `'apiCalls'` and the split happens per request.
+ */
+export declare function meteredQuotaTypeFor(req: Pick<Request, 'user'>, quotaType: QuotaType): QuotaType;
+/** Why a request is not metered/checked against apiCalls (see {@link callQuotaExemption}). */
+export type CallQuotaExemption = 'service' | 'impersonation' | 'on_behalf';
+/**
+ * Whether the apiCalls/automationCalls meter AND check skip this (verified)
+ * request, and why. One function for both halves, so the gate never refuses a
+ * call the meter would not bill:
+ *  - `service` — an internal service principal: peer traffic is caused by a
+ *    user action the originating service already metered;
+ *  - `impersonation` — a sysadmin impersonation session (`impersonatorId`).
+ *    Vendor staff looking at a tenant's console must neither spend the tenant's
+ *    budget nor be locked out by it while diagnosing an exhausted org; the
+ *    session is audited on its own trail;
+ *  - `on_behalf` — a user token FORWARDED by an internal service as part of a
+ *    request already metered where it arrived (the ask agent's tools,
+ *    pipeline's placeholder-plugin confirm), proven by a signed marker the
+ *    user cannot forge (middleware/on-behalf.ts).
+ * Applies to the CALL budgets only: reservation-gated quotas (pipelines,
+ * plugins …) are charged whoever asks. `aiCalls` mirrors the impersonation half
+ * on its own (api-server `withAiCallReservation` skips the slot when the
+ * session is an impersonation; the call is still audited).
+ */
+export declare function callQuotaExemption(req: Request): CallQuotaExemption | undefined;
 /**
  * Service-principal `Authorization` header for a quota call made on behalf of
  * `orgId` by the CURRENT service (`SERVICE_NAME`, the same identity the health
@@ -30,6 +131,16 @@ export interface QuotaReserveResult {
      * 503 instead of a misleading 429 "quota exceeded".
      */
     unavailable?: boolean;
+    /**
+     * Set when an `aiCalls` reservation was refused by one of the org's OPTIONAL
+     * AI controls rather than the period cap: {@link ErrorCode.AI_MEMBER_SHARE_EXCEEDED}
+     * (the caller's per-member share is spent) or
+     * {@link ErrorCode.AI_TOKEN_BUDGET_EXCEEDED} (the org's per-period token
+     * budget is spent). Paired with `exceeded: true` and the quota service's
+     * `message`; {@link sendQuotaReserveDenied} relays both.
+     */
+    code?: AiLimitCode;
+    message?: string;
     quota: {
         type: QuotaType;
         limit: number;
@@ -38,14 +149,32 @@ export interface QuotaReserveResult {
         resetAt?: string;
     };
 }
+/** The 429 codes an `aiCalls` reservation answers when an optional org AI control refuses it. */
+export type AiLimitCode = ErrorCode.AI_MEMBER_SHARE_EXCEEDED | ErrorCode.AI_TOKEN_BUDGET_EXCEEDED;
 /**
  * Quota service client interface.
  */
 export interface QuotaService {
     /** Check if quota is available (fail-open on error). */
     check(orgId: string, quotaType: QuotaType, authHeader: string, requestId?: string): Promise<QuotaCheckResult>;
-    /** Increment quota usage. Returns a promise so callers can optionally handle errors. */
-    increment(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, requestId?: string): Promise<void>;
+    /**
+     * Increment quota usage. Returns a promise so callers can optionally handle
+     * errors. `attribution` defaults to the ambient request context.
+     */
+    increment(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, attribution?: QuotaUsageAttribution): Promise<void>;
+    /**
+     * METERED increment of a pre-aggregated batch (the per-pod batcher's flush,
+     * see `quota-increment-batcher.ts`): the sum of `groups` is applied with
+     * PARTIAL admission — the counter moves by as much as fits under the cap and
+     * the remainder is recorded as `overshoot` — and each group's attribution is
+     * written to the usage ledger. Never a 429. Resolves with what was counted,
+     * or `null` when the quota service did not answer ok (counted on
+     * `quota_increment_failures_total`).
+     */
+    incrementMetered(orgId: string, quotaType: QuotaType, authHeader: string, groups: MeteredIncrementGroup[]): Promise<{
+        counted: number;
+        overshoot: number;
+    } | null>;
     /**
      * Atomic reserve  the same atomic check+increment as `increment`, but
      * parses the response so callers can see whether the slot was actually
@@ -56,7 +185,7 @@ export interface QuotaService {
      * unreachable, timeout, open circuit, non-ok, or a non-quota 429 — unless
      * `QUOTA_RESERVE_FAIL_OPEN=true` (see the policy note at the top of this file).
      */
-    reserve(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, requestId?: string): Promise<QuotaReserveResult>;
+    reserve(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, attribution?: QuotaUsageAttribution): Promise<QuotaReserveResult>;
     /**
      * Roll back a previously reserved slot. Fire-and-forget — never throws.
      * Pass `resetAtSnapshot` (the `quota.resetAt` observed when the slot was
@@ -64,7 +193,16 @@ export interface QuotaService {
      * between reserve and rollback, the server skips the decrement so it doesn't
      * steal capacity from the new period.
      */
-    decrement(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, resetAtSnapshot?: string, requestId?: string): Promise<void>;
+    decrement(orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, resetAtSnapshot?: string, attribution?: QuotaUsageAttribution): Promise<void>;
+    /**
+     * Record what an AI call COST after it settled — its token counts — in the
+     * usage ledger, without moving any counter (a zero-unit ledger row carrying
+     * `tokensIn` / `tokensOut` under the call's attribution). Also how a call that
+     * spent NO `aiCalls` unit (a BYOK key, an impersonation session, a weight-0
+     * model) still shows up in the usage breakdown. Fire-and-forget — never throws.
+     * Optional so test doubles need not implement it.
+     */
+    reportUsage?(orgId: string, quotaType: QuotaType, authHeader: string, tokens: QuotaTokenUsage, attribution?: QuotaUsageAttribution): Promise<void>;
     /**
      * Get the org's quota `QuotaTier`. Used by the plugin-build queue partitioning
      * to route a build to the right per-tier queue. Fail-open returns `DEFAULT_TIER`
@@ -116,20 +254,26 @@ export interface QuotaServiceConfig {
  */
 export declare function createQuotaService(config?: QuotaServiceConfig): QuotaService;
 /**
- * Fire-and-forget quota METERING increment with standardized error logging.
+ * Fire-and-forget quota METERING increment.
+ *
+ * Buffered: the unit joins the pod's per-(org, type) aggregate and is sent with
+ * the next flush (`QUOTA_INCREMENT_FLUSH_MS`, see quota-increment-batcher.ts)
+ * as one metered increment — partial admission against the cap, the excess
+ * recorded as `overshoot`. The counter therefore lags by at most one flush
+ * interval. Only the request meter uses this; reservations stay synchronous.
  *
  * Authenticates as the calling SERVICE ({@link getQuotaServiceAuthHeader}), never
- * with the end user's token: `/quotas/:orgId/increment` is service-principal /
- * system-admin only, so a forwarded user JWT was always rejected (403) and the
- * metered quota (e.g. `apiCalls`, and the `api_pack` bundle raising it) never
- * moved.
+ * with the end user's token: `/quotas/:orgId/increment` is service-principal
+ * only, so a forwarded user JWT was always rejected (403) and the metered quota
+ * (e.g. `apiCalls`, and the `api_pack` bundle raising it) never moved.
  *
  * @param quotaService - Quota service client
  * @param orgId - Organization ID whose counter is incremented
  * @param quotaType - Quota type to increment
  * @param logWarn - Logging function for warnings
+ * @param attribution - Who spent the unit (defaults to the ambient request context)
  */
-export declare function incrementQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, logWarn: (message: string, data?: unknown) => void): void;
+export declare function incrementQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, logWarn: (message: string, data?: unknown) => void, attribution?: QuotaUsageAttribution): void;
 /**
  * Atomic reserve helper for the "reserve + commit / rollback" pattern.
  * Use for expensive resources (pipelines, plugins, AI calls) where the
@@ -151,7 +295,7 @@ export declare function incrementQuota(quotaService: QuotaService, orgId: string
  * }
  * ```
  */
-export declare function reserveQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, requestId?: string): Promise<QuotaReserveResult>;
+export declare function reserveQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, authHeader: string, amount?: number, attribution?: QuotaUsageAttribution): Promise<QuotaReserveResult>;
 /**
  * Answer a DENIED reservation (`reservation.exceeded === true`).
  *
@@ -166,4 +310,4 @@ export declare function sendQuotaReserveDenied(res: Response, quotaType: QuotaTy
  * Logs on failure but never throws  the action that needed the rollback
  * has already failed, no point compounding the error.
  */
-export declare function decrementQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, authHeader: string, logWarn: (message: string, data?: unknown) => void, amount?: number, resetAtSnapshot?: string): void;
+export declare function decrementQuota(quotaService: QuotaService, orgId: string, quotaType: QuotaType, authHeader: string, logWarn: (message: string, data?: unknown) => void, amount?: number, resetAtSnapshot?: string, attribution?: QuotaUsageAttribution): void;