@rebasepro/server 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/mcp/oauth-metadata.d.ts

@@ -1,20 +1,24 @@
 /**
- * What a token may do at `/mcp`.
+ * What a token may do at `/mcp`: the data-plane scopes its tools need, in the
+ * vocabulary every other credential uses — `data:read`, `data:write`,
+ * `data:delete` — each narrowable to one collection (`data:read:posts`).
  *
- * Two, and no more. RFC 9728 asks `scopes_supported` to be the minimal set that
- * makes the resource usable, and the MCP specification's scope-minimization
- * guidance points the same way: a client that only needs to read should be able
- * to ask for exactly that, and a consent screen listing eleven fine-grained
- * permissions is one nobody reads.
- *
- * They are not a substitute for RLS. A `mcp:read` token still reads through the
- * user's own policies — the scope decides whether the tool exists for this
- * session, the database decides which rows come back.
+ * They are not a substitute for RLS. A `data:read` token still reads through
+ * the user's own policies — the scope decides whether a tool exists for this
+ * session and which collections it reaches; the database decides which rows
+ * come back.
  */
-export declare const MCP_SCOPES: readonly ["mcp:read", "mcp:write"];
+export declare const MCP_SCOPES: readonly ["data:read", "data:write", "data:delete"];
 export type McpScope = (typeof MCP_SCOPES)[number];
 /** The scope a client gets when it asks for nothing in particular. */
-export declare const DEFAULT_MCP_SCOPE = "mcp:read";
+export declare const DEFAULT_MCP_SCOPE = "data:read";
+/**
+ * A scope string as granted before `/mcp` spoke the shared vocabulary, read as
+ * what it granted: `mcp:read` was every read, `mcp:write` every create, change
+ * and delete. Applied to stored refresh grants and to access tokens still in
+ * flight, so a connection made before the change keeps exactly its reach.
+ */
+export declare function upgradeStoredMcpScope(scope: string): string;
 /**
  * The canonical resource identifier for this server's MCP endpoint.
  *
@@ -93,12 +97,13 @@ export declare function redirectUriAllowed(candidate: string, registered: string
  *
  * An unknown scope is dropped rather than refused. RFC 6749 §3.3 allows either,
  * and dropping is what keeps a client that asks for `openid profile email` out
- * of habit from failing to connect at all — it gets the MCP scopes it is
- * entitled to and none of the ones it invented.
+ * of habit from failing to connect at all — it gets the data scopes it is
+ * entitled to and none of the ones it invented. A collection target is kept:
+ * `data:read:posts` is a narrower grant, never a wider one.
  */
 export declare function narrowScope(requested: string | undefined | null): string;
-/** Does a granted scope string carry this permission? */
-export declare function scopeAllows(scope: string, needed: McpScope): boolean;
+/** A granted scope string as the list of scopes it holds. */
+export declare function scopeList(scope: string): string[];
 /**
  * The `WWW-Authenticate` value for an unauthenticated request.
  *

package/dist/mcp/oauth-routes.d.ts

@@ -72,7 +72,13 @@ export declare function createOAuthRoutes(config: OAuthRoutesConfig): Hono<HonoE
  * means a stored row is never itself the hazard.
  */
 export declare function redirectUriProblem(uri: string): string | null;
-/** Human-readable consent lines, one per granted scope. */
+/**
+ * Human-readable consent lines, one per granted scope.
+ *
+ * Worded for the person consenting, not taken from the scope catalogue: what
+ * they need to read here is that the client gets *their own* access and no
+ * more, and which collections it reaches when the grant names some.
+ */
 export declare function describeScopes(scope: string): {
     scope: string;
     description: string;

package/dist/metrics/index.d.ts

@@ -31,11 +31,24 @@ export type MetricSurface = "data" | "auth" | "storage" | "functions" | "admin"
  | "other";
 /** Whether a path is the platform looking in, rather than a request served. */
 export declare function isUncountedPath(pathname: string): boolean;
+/**
+ * How long a query waited for a pooled database connection, in milliseconds —
+ * opening one included, when the pool had to. Labelled by data source. See
+ * `pool-wait.ts`, which records it, and why it matters there.
+ */
+export declare const DB_POOL_WAIT_METRIC = "rebase_db_pool_wait_ms";
+/**
+ * Buckets for {@link DB_POOL_WAIT_METRIC}. A checkout from a pool with an idle
+ * connection takes well under a millisecond, so the low end is finer than a
+ * request's: the interesting number is how much of the tail is above zero.
+ */
+export declare const POOL_WAIT_BUCKETS_MS: number[];
 export declare class MetricsRegistry {
     private requests;
     private latency;
     private gauges;
     private counters;
+    private histograms;
     readonly startedAt: number;
     private static labelKey;
     private static parseLabels;
@@ -51,6 +64,11 @@ export declare class MetricsRegistry {
     recordRequest(labels: Record<string, string>, durationMs: number): void;
     incrementCounter(name: string, labels?: Record<string, string>, by?: number): void;
     setGauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Record one observation in a named histogram. `buckets` are its upper
+     * bounds, fixed by the first observation of the series.
+     */
+    observe(name: string, value: number, labels?: Record<string, string>, buckets?: readonly number[]): void;
     /** Prometheus escaping: backslash, quote and newline, in that order. */
     private static formatLabels;
     /** Group `name -> [[labelKey, value]]` for one-HELP-per-metric rendering. */

package/dist/metrics/pool-wait.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How long queries wait for a pooled database connection.
+ *
+ * A write holds its connection — and its transaction, and the locks it has
+ * taken — for as long as its callbacks run: `beforeSave` runs after the
+ * transaction has begun, `afterSave` before it commits. Callbacks that await
+ * something slow therefore take connections out of the pool for that long, and
+ * once enough of them run at once every other request queues for one. Measured
+ * with the default pool of 20: 25 concurrent saves whose `beforeSave` awaited
+ * 300 ms made an unrelated one-row read wait 290 ms for a connection.
+ *
+ * Nothing else shows that queue. Request latency rises, but so it does for a
+ * slow query; this histogram says how much of a request was spent waiting for
+ * a connection at all. Near zero is a healthy pool.
+ *
+ * @module
+ */
+import { type MetricsRegistry } from "./index.js";
+/** `pg.Pool`'s callback form of `connect`, which `pool.query` uses internally. */
+type ConnectCallback = (err: Error | undefined, client: unknown, done: (release?: unknown) => void) => void;
+/**
+ * `connect` as a `pg.Pool` has it: a promise without a callback, the callback
+ * with one. Both are timed — transactions check out with the first,
+ * `pool.query` with the second.
+ */
+export type PoolConnect = (callback?: ConnectCallback) => Promise<unknown> | void;
+/**
+ * Time every checkout from `pool`, from the call to the moment a connection is
+ * handed over, and report it to `record` in milliseconds. A failed checkout is
+ * not recorded: it is an error, not a wait.
+ *
+ * Wraps `connect` on this pool object only. `false` when the pool has no
+ * `connect` to time (a driver that is not pool-based) or is timed already.
+ */
+export declare function timePoolCheckouts(pool: {
+    connect?: PoolConnect;
+}, record: (waitMs: number) => void): boolean;
+/**
+ * Time the checkouts of every pool-based data source into `registry`'s
+ * {@link DB_POOL_WAIT_METRIC} histogram, labelled by the source's key.
+ */
+export declare function recordPoolWaits(registry: MetricsRegistry, sources: readonly {
+    key: string;
+    connection: {
+        pool?: {
+            connect?: PoolConnect;
+        };
+    };
+}[]): void;
+export {};