@beignet/core 0.0.31 → 0.0.33

package/src/schedules/index.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { runWithResolvedTracingContext } from "../tracing/execution.js";
+import type { TracingPort } from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -134,9 +136,7 @@ export interface ScheduleHandleArgs<S extends ScheduleDef, Ctx> {
    * Parsed schedule payload.
    */
   payload: InferSchedulePayload<S>;
-  /**
-   * Handler context.
-   */
+  /** Handler context. */
   ctx: Ctx;
   /**
    * Run metadata.
@@ -219,10 +219,10 @@ export type ScheduleRunArgs<
   Ctx,
   Payload = unknown,
 > = ScheduleRunOptions<Payload> & {
-  /**
-   * Handler context.
-   */
-  ctx: Ctx;
+  /** Handler context or factory resolved inside the schedule span. */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
 };
 
 /**
@@ -374,6 +374,8 @@ export interface InlineScheduleRunnerOptions<Ctx> {
    * Static schedule context or factory evaluated for each run.
    */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
   /**
    * Clock used when run timestamps are not provided.
    */
@@ -575,14 +577,33 @@ function createRunContext(
   };
 }
 
-async function resolveCtx<Ctx>(
-  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
-): Promise<Ctx> {
-  if (typeof ctx === "function") {
-    return (ctx as () => MaybePromise<Ctx>)();
-  }
+function scheduleTraceOperation(
+  schedule: ScheduleDef,
+  options: ScheduleRunOptions<unknown>,
+) {
+  const attributes = {
+    "beignet.schedule.name": schedule.name,
+    ...(options.attempt === undefined
+      ? {}
+      : { "beignet.schedule.attempt": options.attempt }),
+    ...(options.source === undefined
+      ? {}
+      : { "beignet.schedule.source": options.source }),
+  } as const;
+  const metricAttributes = {
+    "beignet.schedule.name": schedule.name,
+    ...(options.attempt === undefined
+      ? {}
+      : { "beignet.schedule.attempt": options.attempt }),
+  } as const;
 
-  return ctx as Ctx;
+  return {
+    name: `beignet.schedule ${schedule.name}`,
+    type: "schedule" as const,
+    kind: "consumer" as const,
+    attributes,
+    metricAttributes,
+  };
 }
 
 async function resolveSchedulePayload<S extends ScheduleDef>(
@@ -739,14 +760,21 @@ export async function runSchedule<
   schedule: S,
   args: ScheduleRunArgs<Ctx, InferSchedulePayload<S>>,
 ): Promise<void> {
-  const run = createRunContext(args, () => new Date());
-  const payload = await resolveSchedulePayload(schedule, args, run);
-
-  await schedule.handle({
-    schedule,
-    payload,
+  await runWithResolvedTracingContext({
+    tracing: args.tracing,
     ctx: args.ctx,
-    run,
+    operation: scheduleTraceOperation(schedule, args),
+    run: async (ctx) => {
+      const run = createRunContext(args, () => new Date());
+      const payload = await resolveSchedulePayload(schedule, args, run);
+
+      await schedule.handle({
+        schedule,
+        payload,
+        ctx,
+        run,
+      });
+    },
   });
 }
 
@@ -780,11 +808,17 @@ export function createInlineScheduleRunner<Ctx>(
           options.onHookError,
           lifecycleArgs,
         );
-        await schedule.handle({
-          schedule,
-          payload,
-          ctx: await resolveCtx(options.ctx),
-          run,
+        await runWithResolvedTracingContext({
+          tracing: options.tracing,
+          ctx: options.ctx as Ctx | (() => MaybePromise<Ctx>),
+          operation: scheduleTraceOperation(schedule, runOptions),
+          run: (ctx) =>
+            schedule.handle({
+              schedule,
+              payload: payload as InferSchedulePayload<S>,
+              ctx,
+              run,
+            }),
         });
         await recordScheduleEvent(options, schedule, "completed", run, {
           payload,

package/src/search/index.ts

@@ -47,6 +47,7 @@ type SearchField<TDocument extends SearchDocumentBase> = Extract<
 export type SearchIndexDef<
   TDocument extends SearchDocumentBase = SearchDocument,
 > = {
+  kind: "search-index";
   name: string;
   primaryKey: SearchField<TDocument>;
   searchableAttributes?: readonly SearchField<TDocument>[];
@@ -60,7 +61,7 @@ export type SearchIndexDef<
  * Options accepted when defining a search index.
  */
 export type DefineSearchIndexOptions<TDocument extends SearchDocumentBase> =
-  Omit<SearchIndexDef<TDocument>, "name" | "primaryKey"> & {
+  Omit<SearchIndexDef<TDocument>, "kind" | "name" | "primaryKey"> & {
     primaryKey?: SearchField<TDocument>;
   };
 
@@ -216,6 +217,7 @@ export function defineSearchIndex<
   if (!name) throw new SearchOptionsError("Search index name is required.");
 
   return {
+    kind: "search-index",
     name,
     primaryKey: options.primaryKey ?? ("id" as SearchField<TDocument>),
     searchableAttributes: options.searchableAttributes,

package/src/server/hooks/index.ts

@@ -46,6 +46,16 @@ export {
   type RateLimitIpSource,
   type RateLimitOptions,
 } from "./rate-limit.js";
+export {
+  applySecurityHeaders,
+  type CsrfFailureReason,
+  type CsrfHooksOptions,
+  type CsrfTokenOptions,
+  createCsrfHooks,
+  createSecurityHeadersHooks,
+  type SecurityHeadersOptions,
+  type StrictTransportSecurityOptions,
+} from "./security.js";
 
 /**
  * Flatten hook arrays into a single hook list.

package/src/server/hooks/rate-limit.ts

@@ -9,6 +9,11 @@ import {
   createProviderInstrumentation,
   type ProviderInstrumentationTarget,
 } from "../../providers/index.js";
+import {
+  resolveTrustedClientIp,
+  type TrustedProxyClientIpSource,
+  type TrustedProxyConfig,
+} from "../trusted-proxy.js";
 import type { HttpRequestLike, ServerHook } from "../types.js";
 
 /**
@@ -40,14 +45,11 @@ type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
  * - `"x-forwarded-for-first"`: the first `x-forwarded-for` entry. This value
  *   is client-controlled, so only use it when a trusted edge normalizes the
  *   header before it reaches the app.
+ * - `"x-real-ip"` and `"cf-connecting-ip"`: dedicated platform headers.
  * - A function receives the raw request and returns the client IP, for
- *   platform-specific headers such as `cf-connecting-ip`.
+ *   platform-specific resolution.
  */
-export type RateLimitIpSource =
-  | "none"
-  | "x-forwarded-for-last"
-  | "x-forwarded-for-first"
-  | ((req: HttpRequestLike) => string | undefined);
+export type RateLimitIpSource = "none" | TrustedProxyClientIpSource;
 
 /**
  * Options for `createRateLimitHooks(...)`.
@@ -76,42 +78,40 @@ export interface RateLimitOptions<Ctx> {
    * Resolve the client IP for `ip`-scoped limits.
    *
    * There is no default: when any contract declares an `ip`-scoped rate limit
-   * and neither `ipSource` nor a custom `earlyKey` is configured, the hook
-   * fails at startup. Pass an explicit trusted proxy strategy, a function for
-   * platform-specific headers, or `"none"` to explicitly accept one shared
+   * and neither `trustedProxy.clientIp`, `ipSource`, nor a custom `earlyKey`
+   * is configured, the hook fails at startup. Prefer `trustedProxy.clientIp`
+   * for production proxy headers; keep `ipSource` for custom keying or
+   * compatibility, or pass `"none"` to explicitly accept one shared
    * `ip:unknown` bucket for all clients.
    */
   ipSource?: RateLimitIpSource;
-}
-
-function parseForwardedFor(req: HttpRequestLike): string[] {
-  const header = req.headers.get("x-forwarded-for") ?? "";
-  return header
-    .split(",")
-    .map((entry) => entry.trim())
-    .filter(Boolean);
+  /**
+   * Shared trusted-proxy policy used to resolve client IPs when `ipSource` is
+   * not set.
+   *
+   * Configure this only when the app is always behind a platform or reverse
+   * proxy that strips or normalizes forwarding headers. For `ip`-scoped rate
+   * limits, set `trustedProxy.clientIp` to the header source written by that
+   * trusted edge.
+   */
+  trustedProxy?: TrustedProxyConfig;
 }
 
 function resolveClientIp(
   req: HttpRequestLike,
   ipSource: RateLimitIpSource,
 ): string | undefined {
-  if (typeof ipSource === "function") {
-    return ipSource(req) || undefined;
-  }
-
   if (ipSource === "none") {
     return undefined;
   }
+  return resolveTrustedClientIp(req, ipSource);
+}
 
-  const entries = parseForwardedFor(req);
-  if (entries.length === 0) {
-    return undefined;
-  }
-
-  return ipSource === "x-forwarded-for-first"
-    ? entries[0]
-    : entries[entries.length - 1];
+function hasTrustedProxyClientIp(
+  config: TrustedProxyConfig | undefined,
+): boolean {
+  if (!config) return false;
+  return Boolean(config.clientIp);
 }
 
 function formatContractNames(names: readonly string[]): string {
@@ -120,10 +120,9 @@ function formatContractNames(names: readonly string[]): string {
 
 function ipSourceConfigurationError(contractNames: string): Error {
   return new Error(
-    `createRateLimitHooks(...) has no ipSource configured, but contract(s) ${contractNames} declare an "ip"-scoped rate limit. ` +
-      `Set ipSource to "x-forwarded-for-last" (app is always behind a trusted reverse proxy that appends the socket address), ` +
-      `"x-forwarded-for-first" (a trusted edge normalizes the header before it reaches the app), ` +
-      `a function for platform-specific headers such as cf-connecting-ip, ` +
+    `createRateLimitHooks(...) has no client IP source configured, but contract(s) ${contractNames} declare an "ip"-scoped rate limit. ` +
+      `Set trustedProxy.clientIp or ipSource to a header source written by a trusted edge, ` +
+      `for example "x-forwarded-for-last", "x-forwarded-for-first", "x-real-ip", "cf-connecting-ip", or a custom function, ` +
       `or "none" to explicitly accept one shared ip:unknown bucket for all clients.`,
   );
 }
@@ -240,14 +239,14 @@ async function enforceRateLimit(
  * never sent to clients; denials emit a `rateLimit.denied` instrumentation
  * event that carries the key for operators.
  *
- * `ip`-scoped limits require an explicit `ipSource` (or a custom `earlyKey`):
- * the hook's `validate` phase fails `createServer(...)` startup when a
- * registered contract declares an `ip` scope without one, instead of silently
- * collapsing all clients into a shared `ip:unknown` bucket. Contracts added
- * later through `server.route(...)` are not visible to `validate`, so
- * enforcing an `ip`-scoped limit without an `ipSource` throws the same
- * configuration error at request time as a backstop. Pass `ipSource: "none"`
- * to explicitly opt in to the shared `ip:unknown` bucket.
+ * `ip`-scoped limits require an explicit `trustedProxy.clientIp`, `ipSource`,
+ * or custom `earlyKey`: the hook's `validate` phase fails `createServer(...)`
+ * startup when a registered contract declares an `ip` scope without one,
+ * instead of silently collapsing all clients into a shared `ip:unknown` bucket.
+ * Contracts added later through `server.route(...)` are not visible to
+ * `validate`, so enforcing an `ip`-scoped limit without a client-IP source
+ * throws the same configuration error at request time as a backstop. Pass
+ * `ipSource: "none"` to explicitly opt in to the shared `ip:unknown` bucket.
  *
  * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
@@ -255,21 +254,28 @@ async function enforceRateLimit(
 export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   options: RateLimitOptions<Ctx> = {},
 ): ServerHook<Ctx, RateLimitPorts> {
-  const { ipSource } = options;
+  const { ipSource, trustedProxy } = options;
   const getClientIp = (
     req: HttpRequestLike,
     contractName: string,
   ): string | undefined => {
-    if (ipSource === undefined) {
-      throw ipSourceConfigurationError(formatContractNames([contractName]));
+    if (ipSource !== undefined) {
+      return resolveClientIp(req, ipSource);
+    }
+    if (hasTrustedProxyClientIp(trustedProxy) && trustedProxy) {
+      return resolveTrustedClientIp(req, trustedProxy.clientIp);
     }
-    return resolveClientIp(req, ipSource);
+    throw ipSourceConfigurationError(formatContractNames([contractName]));
   };
 
   return {
     name: "rate-limit",
     validate: ({ contracts }) => {
-      if (ipSource !== undefined || options.earlyKey) {
+      if (
+        ipSource !== undefined ||
+        hasTrustedProxyClientIp(trustedProxy) ||
+        options.earlyKey
+      ) {
         return;
       }
       const ipScoped = contracts