@beignet/core 0.0.1

package/src/server/http.ts

@@ -0,0 +1,189 @@
+import type {
+  HttpContractConfig,
+  InferHeaderSchemaOutput,
+  InferOutput,
+  StandardSchema,
+} from "../contracts";
+import type { AnyPorts } from "../ports";
+
+export interface HttpRequestLike {
+  method: string;
+  url: string;
+  headers: Headers;
+  /**
+   * The platform request when an adapter has one available.
+   *
+   * Use this as an escape hatch for platform-specific APIs. Prefer the
+   * framework-agnostic methods below when possible.
+   */
+  raw?: Request;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+  arrayBuffer?(): Promise<ArrayBuffer>;
+  blob?(): Promise<Blob>;
+  formData?(): Promise<FormData>;
+  clone?(): HttpRequestLike;
+}
+
+export interface HttpResponseLike {
+  status: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export type HttpResponse = HttpResponseLike | Response;
+
+type InferSchemaOrFallback<
+  T extends StandardSchema | null,
+  Fallback,
+> = T extends StandardSchema ? InferOutput<T> : Fallback;
+
+export type InferPath<C extends HttpContractConfig> = InferSchemaOrFallback<
+  C["pathParams"],
+  Record<string, string>
+>;
+
+export type InferQuery<C extends HttpContractConfig> = InferSchemaOrFallback<
+  C["query"],
+  Record<string, string | string[]>
+>;
+
+export type InferBody<C extends HttpContractConfig> = InferSchemaOrFallback<
+  C["body"],
+  unknown
+>;
+
+export type InferHeaders<C extends HttpContractConfig> =
+  InferHeaderSchemaOutput<Exclude<C["headers"], undefined>> extends undefined
+    ? Record<string, string>
+    : InferHeaderSchemaOutput<Exclude<C["headers"], undefined>>;
+
+export interface HandlerArgs<Ctx, C extends HttpContractConfig> {
+  req: HttpRequestLike;
+  ctx: Ctx;
+  contract: C;
+
+  // inferred from contract schemas
+  path: InferPath<C>;
+  query: InferQuery<C>;
+  headers: InferHeaders<C>;
+  body: InferBody<C>;
+}
+
+export type Handler<Ctx, C extends HttpContractConfig> = (
+  args: HandlerArgs<Ctx, C>,
+) => Promise<HttpResponse> | HttpResponse;
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type OnRequestHook<
+  Ports extends AnyPorts = AnyPorts,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  req: HttpRequestLike;
+  ports: Ports;
+  contract: C;
+  params: Record<string, string>;
+}) => MaybePromise<HttpResponse | undefined>;
+
+export type BeforeHandleResult<Ctx> =
+  | undefined
+  | HttpResponse
+  | {
+      ctx?: Ctx;
+      response?: HttpResponse;
+    };
+
+export type BeforeHandleHook<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  req: HttpRequestLike;
+  ctx: Ctx;
+  contract: C;
+  path: InferPath<C>;
+  query: InferQuery<C>;
+  headers: InferHeaders<C>;
+  body: InferBody<C>;
+}) => MaybePromise<BeforeHandleResult<Ctx>>;
+
+export type BeforeSendHook<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  req: HttpRequestLike;
+  ctx?: Ctx;
+  contract: C;
+  path?: InferPath<C>;
+  query?: InferQuery<C>;
+  headers?: InferHeaders<C>;
+  body?: InferBody<C>;
+  response: HttpResponseLike;
+  error?: unknown;
+}) => MaybePromise<HttpResponseLike | undefined>;
+
+export type AfterSendHook<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  req: HttpRequestLike;
+  ctx?: Ctx;
+  contract: C;
+  path?: InferPath<C>;
+  query?: InferQuery<C>;
+  headers?: InferHeaders<C>;
+  body?: InferBody<C>;
+  response: HttpResponseLike;
+  error?: unknown;
+  durationMs: number;
+}) => MaybePromise<void>;
+
+export type ServerCaughtErrorHook<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  err: unknown;
+  req: HttpRequestLike;
+  ctx?: Ctx;
+  contract: C;
+  path?: InferPath<C>;
+  query?: InferQuery<C>;
+  headers?: InferHeaders<C>;
+  body?: InferBody<C>;
+}) => MaybePromise<void>;
+
+export type ServerUnhandledErrorMapper<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = (args: {
+  err: unknown;
+  req: HttpRequestLike;
+  ctx?: Ctx;
+  contract: C;
+  path?: InferPath<C>;
+  query?: InferQuery<C>;
+  headers?: InferHeaders<C>;
+  body?: InferBody<C>;
+}) => MaybePromise<HttpResponse | undefined>;
+
+export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
+  name?: string;
+  onRequest?: OnRequestHook<Ports>;
+  beforeHandle?: BeforeHandleHook<Ctx>;
+  beforeSend?: BeforeSendHook<Ctx>;
+  afterSend?: AfterSendHook<Ctx>;
+  onCaughtError?: ServerCaughtErrorHook<Ctx>;
+  mapUnhandledError?: ServerUnhandledErrorMapper<Ctx>;
+}
+
+export type ResolvedRoute<_Ctx, C extends HttpContractConfig> = {
+  contract: C;
+  handler: (
+    req: HttpRequestLike,
+    params?: Record<string, string>,
+  ) => Promise<HttpResponse>;
+  match: (
+    method: string,
+    pathname: string,
+  ) => { matched: true } | { matched: false };
+};

package/src/server/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @beignet/core/server
+ *
+ * Framework-agnostic HTTP server runtime for Beignet.
+ * Shared by Beignet server adapters.
+ */
+
+// Re-export types from dependencies for convenience
+export type {
+  HttpContractConfig,
+  InferOutput,
+  StandardSchema,
+  StandardSchemaV1,
+} from "../contracts";
+export { AppError } from "../errors";
+export type { AnyPorts } from "../ports";
+export type { ServiceProvider } from "../providers";
+export * from "./health";
+export * from "./hooks";
+export * from "./http";
+export * from "./openapi";
+export * from "./providers";
+export type {
+  CreateServerOptions,
+  RouteDef,
+  RouteGroup,
+  ServerInstance,
+} from "./server";
+export {
+  contractsFromRoutes,
+  createServer,
+  defineRouteGroup,
+  defineRoutes,
+} from "./server";
+export * from "./types";

package/src/server/openapi.ts

@@ -0,0 +1,72 @@
+/**
+ * OpenAPI generation handler
+ * OpenAPI helpers for the Beignet server runtime.
+ */
+
+import type { HttpContractConfig } from "../contracts";
+import type { AppEnvironment } from "./health";
+import type { HttpRequestLike, HttpResponseLike } from "./types";
+
+/**
+ * OpenAPI configuration
+ */
+export interface OpenAPIConfig {
+  /** Enable OpenAPI endpoint (default: false) */
+  enabled?: boolean;
+  /**
+   * Suggested path for the OpenAPI endpoint (e.g., "/api/openapi.json").
+   * NOTE: This field is for documentation/metadata only and does not control routing.
+   * You must manually wire the openapiHandler to your desired route.
+   */
+  suggestedPath?: string;
+  /** API title */
+  title?: string;
+  /** API version */
+  version?: string;
+  /** API description */
+  description?: string;
+}
+
+/**
+ * Create an OpenAPI handler
+ * Returns a function that can be called with an HttpRequestLike to get an HttpResponseLike
+ */
+export function createOpenAPIHandler(
+  contracts: readonly HttpContractConfig[],
+  openapiConfig: OpenAPIConfig | undefined,
+  _env: AppEnvironment,
+): (req: HttpRequestLike) => Promise<HttpResponseLike> {
+  // Lazily generate OpenAPI spec on first request
+  let cachedSpec: object | null = null;
+
+  return async (_req: HttpRequestLike): Promise<HttpResponseLike> => {
+    // Generate spec if not cached
+    if (!cachedSpec) {
+      try {
+        // Dynamic import to avoid hard dependency
+        const { contractsToOpenAPI } = await import("../openapi");
+        cachedSpec = contractsToOpenAPI(contracts, {
+          title: openapiConfig?.title ?? "Beignet API",
+          version: openapiConfig?.version ?? "1.0.0",
+          description: openapiConfig?.description,
+        });
+      } catch (error) {
+        // OpenAPI generation failed
+        return {
+          status: 500,
+          body: {
+            error: "OpenAPI generation failed",
+            message: error instanceof Error ? error.message : "Unknown error",
+          },
+          headers: { "Content-Type": "application/json" },
+        };
+      }
+    }
+
+    return {
+      status: 200,
+      body: cachedSpec,
+      headers: { "Content-Type": "application/json" },
+    };
+  };
+}

package/src/server/providers/index.ts

@@ -0,0 +1,3 @@
+export { ConfigValidationError, readEnv } from "../../config";
+export { SchemaValidationError } from "../../errors";
+export { loadProviderConfig, parseStandardSchema } from "./loadProviderConfig";

package/src/server/providers/loadProviderConfig.ts

@@ -0,0 +1,72 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  ConfigValidationError,
+  parseStandardSchemaAsync,
+  readEnv,
+} from "../../config";
+import { SchemaValidationError } from "../../errors";
+import type { AnyPorts } from "../../ports";
+import type { ServiceProvider } from "../../providers";
+
+type ProviderConfigDef<Schema extends StandardSchemaV1<unknown, unknown>> = {
+  schema: Schema;
+  envPrefix?: string;
+};
+
+async function parseStandardSchema<
+  Schema extends StandardSchemaV1<unknown, unknown>,
+>(
+  schema: Schema,
+  input: unknown,
+): Promise<StandardSchemaV1.InferOutput<Schema>> {
+  try {
+    return await parseStandardSchemaAsync(schema, input);
+  } catch (error) {
+    if (error instanceof ConfigValidationError) {
+      throw new SchemaValidationError(error.issues);
+    }
+
+    throw error;
+  }
+}
+
+export async function loadProviderConfig<
+  Ports extends AnyPorts,
+  Schema extends StandardSchemaV1<unknown, unknown>,
+>(
+  provider: ServiceProvider<Ports, Schema>,
+  env: Record<string, string | undefined>,
+  overrides: Record<string, unknown>,
+): Promise<StandardSchemaV1.InferOutput<Schema> | undefined> {
+  const configDef = provider.config as ProviderConfigDef<Schema> | undefined;
+  if (!configDef) return undefined;
+
+  const { schema, envPrefix } = configDef;
+  const hasOverride = Object.hasOwn(overrides, provider.name);
+  const input = hasOverride
+    ? overrides[provider.name]
+    : envPrefix
+      ? readEnv({ env, prefix: envPrefix })
+      : {};
+
+  try {
+    return await parseStandardSchema(schema, input);
+  } catch (error) {
+    const suffix = envPrefix ? ` (envPrefix=${envPrefix})` : "";
+    const found = envPrefix
+      ? Object.keys(env).filter(
+          (k) => k.startsWith(envPrefix) && env[k] !== undefined,
+        )
+      : [];
+    const hint = envPrefix
+      ? found.length
+        ? `\n  Env vars found with prefix "${envPrefix}": ${found.join(", ")}`
+        : `\n  No env vars found with prefix "${envPrefix}"`
+      : "";
+    throw new Error(
+      `Failed to load config for provider "${provider.name}"${suffix}: ${(error as Error).message}${hint}`,
+    );
+  }
+}
+
+export { parseStandardSchema };