@tempoxyz/id 0.0.0-stage → 0.0.1

package/dist/internal/TempoAccount.js

@@ -0,0 +1,369 @@
+/**
+ * Each user's Tempo Accounts: configurable accounts (TIP-1107), each in one realm and owned by one
+ * key. Each kind in {@link kinds}, such as Privy wallets and passkeys, lists the
+ * keys of its kind, and a kind that creates keys creates a user's first account. The key acts as the
+ * account on each chain, except on the chains that `CONFIGURABLE_ACCOUNTS` names, where the account
+ * is configurable, as `ConfigurableAccount` describes. A request names the chain it acts on, and the
+ * owners carry their view of that chain.
+ * @module
+ */
+import { and, eq, inArray, notExists, sql } from 'drizzle-orm';
+import { createMiddleware } from 'hono/factory';
+import { AccountConfig } from 'viem/tempo';
+import { z } from 'zod';
+import * as Schema from '../app/db/schema.js';
+import * as ConfigurableAccount from './ConfigurableAccount.js';
+import * as ErrorResponse from './ErrorResponse.js';
+import * as Owner from './Owner.js';
+import * as Passkey from './owners/Passkey.js';
+import * as Privy from './owners/Privy.js';
+import * as Secp256k1 from './owners/Secp256k1.js';
+import * as Timing from './Timing.js';
+/** The request names a Tempo Account that is not one of the user's in the app's realms. */
+export class ForeignAccountError extends ErrorResponse.define('foreign_account') {
+    name = 'TempoAccount.ForeignAccountError';
+    constructor(options) {
+        super({
+            error_description: `Access denied to Tempo Account ${options.account}. Name one of the user's accounts in the app's realms.`,
+            field: options.field ?? 'account',
+            meta: { account: options.account },
+        });
+    }
+}
+/**
+ * The kinds of owner keys, in the order that breaks a tie in creation time: a passkey comes before a
+ * Privy wallet created in the same second, and a Privy wallet before a secp256k1 key. The first kind
+ * that creates keys in a realm creates a user's first account there, so a realm with a Privy app
+ * creates Privy wallets even where it also holds secp256k1 owners.
+ */
+export const kinds = [Passkey.owner, Privy.owner, Secp256k1.owner];
+/** Zod schemas for Tempo Accounts as the API returns them. */
+export var schema;
+(function (schema) {
+    const address = z
+        .templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]{40}$/)])
+        .meta({
+        description: 'A 20-byte address.',
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+    });
+    /** A realm, with its display name. */
+    schema.realm = z
+        .object({
+        id: z.string().meta({
+            description: 'The realm ID, such as `default` or `tempo-cash`.',
+            examples: ['tempo-cash'],
+        }),
+        name: z.string().meta({
+            description: 'The realm display name, such as `Tempo Cash`.',
+            examples: ['Tempo Cash'],
+        }),
+    })
+        .meta({
+        description: 'A realm, which holds Tempo Accounts. An app reaches only the accounts of its realms.',
+        id: 'Realm',
+    });
+    /** A Tempo Account, with its configuration and its realm. */
+    schema.tempoAccount = z
+        .object({
+        address: address.meta({
+            description: "The address on the request's chain: the owner key's address, or the initial configuration's address on a chain with configurable accounts. A linked wallet.tempo passkey keeps its own address, also after its upgrade.",
+            examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+        }),
+        config: z
+            .object({
+            chainId: z
+                .number()
+                .int()
+                .optional()
+                .meta({
+                description: 'The ID of the chain where the configuration applies, which the request named. Absent on a chain whose accounts are not configurable, and for a wallet.tempo passkey that no upgrade made configurable.',
+                examples: [31318],
+            }),
+            owners: z
+                .array(z
+                .object({
+                owner: address.meta({
+                    description: 'The address of the owner key.',
+                    examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+                }),
+                type: z.enum(kinds.map((kind) => kind.type)).meta({
+                    description: 'Who holds the owner key: a Privy wallet (`privy`), a key that Tempo ID holds in development (`secp256k1`), or a passkey (`webAuthn`), which signs only in the browser.',
+                    examples: ['webAuthn'],
+                }),
+                weight: z.number().meta({
+                    description: "The owner's signing weight, which counts toward `threshold`.",
+                    examples: [1],
+                }),
+            })
+                .meta({ description: 'One key that signs for the account.' }))
+                .readonly()
+                .meta({ description: 'The keys that sign for the account.' }),
+            salt: z.templateLiteral(['0x', z.string()]).meta({
+                description: 'The 32-byte salt that the account address derives from, as hex.',
+                examples: [`0x${'0'.repeat(64)}`],
+            }),
+            threshold: z.number().meta({
+                description: 'The total owner weight that a signature needs to act for the account.',
+                examples: [1],
+            }),
+            version: z.templateLiteral(['0x', z.string()]).meta({
+                description: 'The configuration version, as a hex quantity.',
+                examples: ['0x0'],
+            }),
+        })
+            .meta({
+            description: 'The account configuration (TIP-1107): its owners, salt, threshold, and version.',
+        }),
+        realm: schema.realm,
+    })
+        .meta({
+        description: 'A configurable Tempo Account (TIP-1107) and its configuration.',
+        id: 'TempoAccount',
+    });
+})(schema || (schema = {}));
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, as {@link held} does, and creates
+ * one in the first realm for a user with none, when a kind creates keys in that realm. On a
+ * deployment with configurable accounts, the new account is configurable from its creation. A user with a
+ * linked owner key, such as a wallet.tempo passkey, receives none. Concurrent calls, through apps
+ * whose realms overlap, and a link at the same time create one account. No database connection
+ * stays open while a kind creates the key.
+ */
+export async function create(c, options) {
+    const { db, realms, userId } = options;
+    const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load');
+    const held = await Timing.measure(c, owners(c, {
+        chainId: options.chainId,
+        db,
+        env: options.env,
+        key: listKey(options),
+        loaded,
+        userId,
+    }), 'TempoAccount.owners');
+    if (held.length > 0)
+        return held;
+    const creator = (realm) => {
+        for (const entry of loaded) {
+            const fn = entry.create?.(realm);
+            if (fn)
+                return fn;
+        }
+        return undefined;
+    };
+    const realm = realms[0];
+    if (!realm || !creator(realm))
+        return [];
+    // A short transaction under the user's lock picks the realm, so the kind's calls after it hold no
+    // database connection. A claim in these realms, from a request through an app whose realms
+    // overlap them, wins over the first realm. A linked key that a kind stored before the claim wins
+    // over both. A link after the claim adds the linked key's account beside the created one.
+    const creates = realms.filter((entry) => creator(entry));
+    const target = await db.transaction(async (tx) => {
+        await Timing.measure(c, Owner.lock(tx, { userId }), 'db.account.lock');
+        const linked = await Timing.measure(c, owners(c, {
+            // The recheck lists a linked key on the chain, as the read before the lock does.
+            chainId: options.chainId,
+            db: tx,
+            env: options.env,
+            loaded: loaded.filter((entry) => !entry.create),
+            userId,
+        }), 'TempoAccount.linked');
+        // Only a claim in a realm where a kind creates keys counts.
+        const claims = tx.$with('claims').as(tx
+            .select({ realmId: Schema.firstAccounts.realmId })
+            .from(Schema.firstAccounts)
+            .where(and(eq(Schema.firstAccounts.userId, userId), inArray(Schema.firstAccounts.realmId, creates.map((entry) => entry.id)))));
+        // One statement reads the claims and, without a claim or a linked key, claims the first realm.
+        // Both parts read the claims as they were before the statement.
+        const claim = tx.$with('claim').as(tx
+            .insert(Schema.firstAccounts)
+            .select(tx
+            .select({
+            createdAt: sql `now()`.as('created_at'),
+            realmId: sql `${realm.id}`.as('realm_id'),
+            userId: Schema.user.id,
+        })
+            .from(Schema.user)
+            .where(and(eq(Schema.user.id, userId), notExists(tx.select().from(claims)))))
+            .onConflictDoNothing()
+            .returning({ realmId: Schema.firstAccounts.realmId }));
+        const rows = await Timing.measure(c, linked.length > 0
+            ? tx.with(claims).select().from(claims)
+            : tx.with(claims, claim).select().from(claims), 'db.account.claims');
+        const claimed = realms.find((entry) => rows.some((row) => row.realmId === entry.id));
+        if (claimed)
+            return { realm: claimed };
+        if (linked.length > 0)
+            return { linked };
+        return { realm };
+    });
+    if ('linked' in target) {
+        // Another request linked a key after the read before the lock, so a later list reads again.
+        c.var.ownerLists?.delete(listKey(options));
+        return target.linked;
+    }
+    const owner = await Timing.measure(c, creator(target.realm)(c), 'TempoAccount.createOwner');
+    // Another request can link a key while the kind creates this one, so a later list reads again.
+    c.var.ownerLists?.delete(listKey(options));
+    // On a chain with configurable accounts, the new key owns the account that its initial
+    // configuration derives, which no row stores.
+    const chain = ConfigurableAccount.on(options);
+    if (!chain)
+        return [owner];
+    return ConfigurableAccount.apply([owner], {
+        chainId: chain.chainId,
+        configs: [],
+    });
+}
+(function (create) {
+    /** The refusals `create` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    create.errors = [
+        ...Passkey.owner.errors,
+        ...Privy.owner.errors,
+        ...Secp256k1.owner.errors,
+    ];
+})(create || (create = {}));
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, oldest first, and creates none.
+ * Each kind reads its keys in parallel.
+ */
+export async function held(c, options) {
+    const loaded = await Timing.measure(c, load(c, options), 'TempoAccount.load');
+    return await Timing.measure(c, owners(c, {
+        chainId: options.chainId,
+        db: options.db,
+        env: options.env,
+        key: listKey(options),
+        loaded,
+        userId: options.userId,
+    }), 'TempoAccount.owners');
+}
+(function (held) {
+    /** The refusals `held` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    held.errors = create.errors;
+})(held || (held = {}));
+/**
+ * Returns the user's Tempo Accounts in `realms`, oldest first, as the API returns them, and creates
+ * none. Their owners are those that {@link held} returns.
+ */
+export async function list(c, options) {
+    const owned = await Timing.measure(c, held(c, options), 'TempoAccount.held');
+    return owned.map(serialize);
+}
+(function (list) {
+    /** The refusals `list` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    list.errors = create.errors;
+})(list || (list = {}));
+/**
+ * Empties the owner keys that the request listed. Call it after a write that changes a user's owner
+ * keys outside {@link create}, such as a passkey's link or registration, so a later list in the same
+ * request reads them again.
+ */
+export function forget(c) {
+    c.var.ownerLists?.clear();
+}
+/**
+ * Sets `c.var.ownerLists` to an empty {@link Lists} for the request, or to the lists of the page's
+ * request for an in-process call of its loader.
+ */
+export const middleware = createMiddleware(async (c, next) => {
+    c.set('ownerLists', c.env.ownerLists ?? new Map());
+    await next();
+});
+/**
+ * Returns the key of the user's lists in `realms` in {@link Lists}. Each kind reads the realms'
+ * configuration, such as a relying party, so the key holds each realm whole.
+ */
+function listKey(options) {
+    return JSON.stringify([
+        options.userId,
+        ...options.realms.map((realm) => [
+            realm.id,
+            realm.name,
+            realm.passkeys?.rpId ?? null,
+            realm.privy?.appId ?? null,
+            realm.secp256k1,
+        ]),
+    ]);
+}
+/** Loads every kind in {@link kinds} for `realms`, in parallel, in the order of {@link kinds}. */
+async function load(c, options) {
+    return await Promise.all(kinds.map((kind) => kind.load(c, options)));
+}
+/**
+ * Returns the keys that `loaded` lists, oldest first, and creates none. The kinds are read in
+ * parallel, and an earlier kind wins a tie. On a deployment with configurable accounts, the user's
+ * stored configurations apply, as `ConfigurableAccount.apply` describes.
+ */
+async function owners(c, options) {
+    const { db, key, userId } = options;
+    const chain = ConfigurableAccount.on(options);
+    const [lists, configs] = await Promise.all([
+        (() => {
+            const read = () => Promise.all(options.loaded.map((entry) => entry.list(c, { db })));
+            const stored = c.var.ownerLists;
+            if (!key || !stored)
+                return read();
+            const listed = stored.get(key);
+            if (listed)
+                return listed;
+            // A failed read stores nothing, so the next list reads again.
+            const reading = read().catch((error) => {
+                if (stored.get(key) === reading)
+                    stored.delete(key);
+                throw error;
+            });
+            stored.set(key, reading);
+            return reading;
+        })(),
+        chain
+            ? Timing.measure(c, ConfigurableAccount.list(db, { chainId: chain.chainId, userId }), 'db.accountConfig.list')
+            : [],
+    ]);
+    const merged = Owner.merge(lists);
+    if (!chain)
+        return merged;
+    return ConfigurableAccount.apply(merged, { chainId: chain.chainId, configs });
+}
+/**
+ * Returns the owner of `account` that signs its keys: a cloud wallet when the account has one, since
+ * Tempo ID signs with it, or else its first owner. A configuration sorts its owners by address, so
+ * the first owner alone does not name it.
+ */
+export function signer(account) {
+    return (account.config.owners.find((entry) => entry.type !== 'webAuthn') ??
+        account.config.owners[0]);
+}
+/**
+ * Returns the Tempo Account that `owner` owns, as the API returns it. A configurable account carries
+ * its configuration on the configurable-accounts chain, with each owner's kind.
+ */
+export function serialize(owner) {
+    const { configurable } = owner;
+    if (configurable) {
+        const config = AccountConfig.toRpc(configurable.owner.account.config);
+        return schema.tempoAccount.parse({
+            address: configurable.owner.account.address,
+            config: {
+                ...config,
+                chainId: configurable.chainId,
+                owners: config.owners.map((entry) => ({
+                    ...entry,
+                    type: configurable.owners.find((candidate) => candidate.address.toLowerCase() === entry.owner.toLowerCase())?.type ?? owner.type,
+                })),
+            },
+            realm: { id: owner.realm.id, name: owner.realm.name },
+        });
+    }
+    const config = AccountConfig.toRpc(owner.account.config);
+    return schema.tempoAccount.parse({
+        // The key acts as the account on every chain where it is not configurable.
+        address: Owner.address(owner),
+        config: {
+            ...config,
+            owners: config.owners.map((entry) => ({ ...entry, type: owner.type })),
+        },
+        realm: { id: owner.realm.id, name: owner.realm.name },
+    });
+}
+//# sourceMappingURL=TempoAccount.js.map

package/dist/internal/TempoAccount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TempoAccount.js","sourceRoot":"","sources":["../../src/internal/TempoAccount.ts"],"names":[],"mappings":"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"}

package/dist/internal/TestInbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Selects the sign-in codes that a deployment sends to its test inbox instead of emailing them. A
+ * preview sets `TEST_EMAIL_DOMAIN` and binds `TEST_INBOX`, so the end-to-end suite reads the codes of
+ * its test addresses, while every other address still receives email. Only domains that RFC 2606
+ * reserves qualify, so no deployment can divert a real address.
+ * @module
+ */
+/** The domains that a test inbox can receive, which RFC 2606 reserves, so no real address uses them. */
+export declare const domains: readonly ['example.com', 'example.net', 'example.org'];
+/** A domain that a test inbox can receive. */
+export type Domain = (typeof domains)[number];
+/** A message to a test inbox, in the shape of Void's development inbox. */
+export type Message = {
+    /** The subject line. */
+    subject: string;
+    /** The plain-text body. */
+    text: string;
+    /** The recipients. */
+    to: readonly {
+        /** The recipient's address. */
+        email: string;
+    }[];
+};
+/** The test inbox's `Capture` entrypoint, which a deployment binds as `TEST_INBOX`. */
+export type Service = {
+    /** Stores `message`. */
+    capture(message: Message): Promise<void>;
+};
+/**
+ * Returns whether `email` belongs at the test inbox: `domain` is one of {@link domains}, and the
+ * address's domain is exactly `domain`. Returns `false` when `domain` is absent.
+ */
+export declare function matches(options: matches.Options): boolean;
+export declare namespace matches {
+    type Options = {
+        /** The deployment's `TEST_EMAIL_DOMAIN`, or `undefined` when it sets none. */
+        domain?: string | undefined;
+        /** The recipient's address. */
+        email: string;
+    };
+}
+//# sourceMappingURL=TestInbox.d.ts.map

package/dist/internal/TestInbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestInbox.d.ts","sourceRoot":"","sources":["../../src/internal/TestInbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wGAAwG;AACxG,eAAO,MAAM,OAAO,YAAI,aAAa,EAAE,aAAa,EAAE,aAAa,CAAU,CAAA;AAE7E,8CAA8C;AAC9C,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7C,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG;IACpB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,EAAE,EAAE,SAAS;QACX,+BAA+B;QAC/B,KAAK,EAAE,MAAM,CAAA;KACd,EAAE,CAAA;CACJ,CAAA;AAED,uFAAuF;AACvF,MAAM,MAAM,OAAO,GAAG;IACpB,wBAAwB;IACxB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACzC,CAAA;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,WAI/C;AAED,MAAM,CAAC,OAAO,WAAW,OAAO,CAAC;IAC/B,KAAK,OAAO,GAAG;QACb,8EAA8E;QAC9E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAC3B,+BAA+B;QAC/B,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;CACF"}

package/dist/internal/TestInbox.js

@@ -0,0 +1,20 @@
+/**
+ * Selects the sign-in codes that a deployment sends to its test inbox instead of emailing them. A
+ * preview sets `TEST_EMAIL_DOMAIN` and binds `TEST_INBOX`, so the end-to-end suite reads the codes of
+ * its test addresses, while every other address still receives email. Only domains that RFC 2606
+ * reserves qualify, so no deployment can divert a real address.
+ * @module
+ */
+/** The domains that a test inbox can receive, which RFC 2606 reserves, so no real address uses them. */
+export const domains = ['example.com', 'example.net', 'example.org'];
+/**
+ * Returns whether `email` belongs at the test inbox: `domain` is one of {@link domains}, and the
+ * address's domain is exactly `domain`. Returns `false` when `domain` is absent.
+ */
+export function matches(options) {
+    const { domain, email } = options;
+    if (!domain || !domains.some((entry) => entry === domain))
+        return false;
+    return email.toLowerCase().endsWith(`@${domain}`);
+}
+//# sourceMappingURL=TestInbox.js.map

package/dist/internal/TestInbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestInbox.js","sourceRoot":"","sources":["../../src/internal/TestInbox.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wGAAwG;AACxG,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,aAAa,EAAE,aAAa,EAAE,aAAa,CAAU,CAAA;AAwB7E;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,OAAwB;IAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IACjC,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IACvE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC,CAAA;AACnD,CAAC"}

package/dist/internal/Timing.d.ts

@@ -0,0 +1,52 @@
+import type { Env } from './Env.js';
+/** One awaited call. */
+export type Span = {
+    /** When the call settled, in the request's sequence of opens and settles. Pending spans hold `Infinity`. */
+    closed: number;
+    /**
+     * What the header shows beside the span, such as an in-process call's path. Logs leave it out,
+     * since a path can carry a device's user code.
+     */
+    description?: string | undefined;
+    /** How long the call took, in milliseconds. */
+    duration: number;
+    /**
+     * `service.operation` for a call to another service, such as `db.session.get`, or
+     * `Module.function` for a step of Tempo ID's own, such as `Session.get`.
+     */
+    name: string;
+    /** When the call's span opened, in the request's sequence of opens and settles. */
+    opened: number;
+    /** When the call started, in milliseconds after the request did. */
+    start: number;
+};
+/** A request's timings, which {@link middleware} creates and {@link measure} appends to. */
+export type Timing = {
+    /** How many spans opened or settled so far, which orders spans that start at the same instant. */
+    events: number;
+    /** The request's spans, in the order they opened. A span still pending has a zero duration. */
+    spans: Span[];
+    /** When the request started, from `performance.now()`. */
+    start: number;
+};
+/**
+ * Awaits `promise` as the span `name`, and returns its result. A rejection is timed too, then
+ * rethrown. Concurrent spans may share a name. The header shows `description` beside the span, and
+ * logs leave it out.
+ */
+export declare function measure<promise extends PromiseLike<unknown>>(c: measure.Context, promise: promise, name: string, description?: string): Promise<Awaited<promise>>;
+export declare namespace measure {
+    /** A context that carries the request's timing, such as a route's or a page loader's. */
+    type Context = {
+        /** The request's variables. */
+        var: Pick<Env['Variables'], 'timing'>;
+    };
+}
+/**
+ * Times the request. Once the response is ready, it appends a `Server-Timing` header with the
+ * request's `total`, the `cold` metric on the isolate's first request, and each span. Outside the
+ * Vite dev server, it also logs the same timings. A streamed page's `total` ends when its headers
+ * are ready.
+ */
+export declare const middleware: import("hono").MiddlewareHandler<Env, string, {}, Response>;
+//# sourceMappingURL=Timing.d.ts.map

package/dist/internal/Timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timing.d.ts","sourceRoot":"","sources":["../../src/internal/Timing.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAGnC,wBAAwB;AACxB,MAAM,MAAM,IAAI,GAAG;IACjB,4GAA4G;IAC5G,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,4FAA4F;AAC5F,MAAM,MAAM,MAAM,GAAG;IACnB,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAA;IACd,+FAA+F;IAC/F,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAQD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,OAAO,SAAS,WAAW,CAAC,OAAO,CAAC,EAChE,CAAC,EAAE,OAAO,CAAC,OAAO,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAkB3B;AAED,MAAM,CAAC,OAAO,WAAW,OAAO,CAAC;IAC/B,yFAAyF;IACzF,KAAK,OAAO,GAAG;QACb,+BAA+B;QAC/B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAA;KACtC,CAAA;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,6DAyCrB,CAAA"}

package/dist/internal/Timing.js

@@ -0,0 +1,116 @@
+/**
+ * Request timings: how long each call that a request awaits takes. The calls range from Tempo ID's
+ * own steps to the Better Auth, database, and email calls inside them. The middleware sends them in
+ * a `Server-Timing` header, which browser developer tools show beside each request. Outside the Vite
+ * dev server, it also logs them with `Log.info`. Workers advance the clock only across I/O, so a span
+ * measures the I/O it awaits, and computation reads as zero. The header also marks the first request
+ * of an isolate, which can wait for the isolate to start, outside every span.
+ * @module
+ */
+import { createMiddleware } from 'hono/factory';
+import * as Log from './Log.js';
+/**
+ * Whether the isolate served a request before. The flag holds no request data, and only the header
+ * of the isolate's first request reads it as `false`.
+ */
+let served = false;
+/**
+ * Awaits `promise` as the span `name`, and returns its result. A rejection is timed too, then
+ * rethrown. Concurrent spans may share a name. The header shows `description` beside the span, and
+ * logs leave it out.
+ */
+export async function measure(c, promise, name, description) {
+    const timing = c.var.timing;
+    const start = performance.now();
+    const span = {
+        closed: Infinity,
+        ...(description ? { description } : {}),
+        duration: 0,
+        name,
+        opened: timing.events++,
+        start: start - timing.start,
+    };
+    timing.spans.push(span);
+    try {
+        return await promise;
+    }
+    finally {
+        span.closed = timing.events++;
+        span.duration = performance.now() - start;
+    }
+}
+/**
+ * Times the request. Once the response is ready, it appends a `Server-Timing` header with the
+ * request's `total`, the `cold` metric on the isolate's first request, and each span. Outside the
+ * Vite dev server, it also logs the same timings. A streamed page's `total` ends when its headers
+ * are ready.
+ */
+export const middleware = createMiddleware(async (c, next) => {
+    const cold = !served;
+    served = true;
+    const timing = { events: 0, spans: [], start: performance.now() };
+    c.set('timing', timing);
+    await next();
+    const total = performance.now() - timing.start;
+    const spans = order(timing.spans);
+    c.res.headers.append('server-timing', [
+        `total;dur=${round(total)}`,
+        ...(cold ? ['cold'] : []),
+        ...spans.map(serialize),
+    ].join(', '));
+    // The dev server prints every entry to the terminal, and the header carries the same spans.
+    if (Log.dev())
+        return;
+    // Without the context, `Log` leaves the request's path out, since callers control it and it can
+    // carry a user code. The route pattern stands in, and pages without a route share `/*`.
+    Log.info({
+        fields: {
+            duration: round(total),
+            errorCode: c.var.refusal?.error,
+            method: c.req.method,
+            reason: c.var.refusal?.reason,
+            requestId: c.var.requestId,
+            route: Log.route(c),
+            spans: spans
+                .map((span) => `${span.name};dur=${round(span.duration)};start=${round(span.start)}`)
+                .join(', '),
+            status: c.res.status,
+        },
+        message: 'The Worker timed a request.',
+    });
+});
+/**
+ * Orders spans with each step before the calls inside it. The order reads only the sequence of
+ * opens and settles, since the clock can advance between the span of a call and the span of its
+ * step. Spans that open with no settle between them all overlap. Of those, the one that settles
+ * last encloses the others, since a step's promise is created before the step's span opens. Spans
+ * that open after a settle come after.
+ */
+function order(spans) {
+    // `spans` holds the spans in the order they opened, so each event before a span that is not an
+    // earlier span's open is a settle.
+    return spans
+        .map((span, index) => ({ settles: span.opened - index, span }))
+        .toSorted((a, b) => {
+        if (a.settles !== b.settles)
+            return a.settles - b.settles;
+        // Pending spans hold `Infinity`, which subtraction cannot compare.
+        if (a.span.closed !== b.span.closed)
+            return a.span.closed > b.span.closed ? -1 : 1;
+        return a.span.opened - b.span.opened;
+    })
+        .map((entry) => entry.span);
+}
+/** Rounds milliseconds to one decimal. */
+function round(milliseconds) {
+    return Math.round(milliseconds * 10) / 10;
+}
+/** Serializes a span as a `Server-Timing` metric. */
+function serialize(span) {
+    const metric = `${span.name};dur=${round(span.duration)}`;
+    if (!span.description)
+        return metric;
+    // The description is a quoted string, which escapes quotes and backslashes.
+    return `${metric};desc="${span.description.replace(/["\\]/g, '\\$&')}"`;
+}
+//# sourceMappingURL=Timing.js.map

package/dist/internal/Timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timing.js","sourceRoot":"","sources":["../../src/internal/Timing.ts"],"names":[],"mappings":"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"}