@lovrozagar/honey 0.1.0

package/src/curl-logger.ts

@@ -0,0 +1,235 @@
+import type { MiddlewareFn } from "./middleware.ts"
+import type { LoggerInstance } from "./logger.ts"
+
+type BodyOmittedReason =
+	| "content-type"
+	| "disabled"
+	| "missing"
+	| "read-error"
+	| "too-large"
+
+type CurlLogData = {
+	bodyIncluded: boolean
+	bodyOmittedReason: BodyOmittedReason | null
+	curl: string
+	duration: number
+	method: string
+	path: string
+	requestId: string | null
+	status: number
+}
+
+type CurlLoggerBodyOptions = {
+	allowContentTypes?: string[]
+	maxBytes?: number
+}
+
+type CurlLoggerOptions = {
+	body?: boolean | CurlLoggerBodyOptions
+	instance?: LoggerInstance
+	log?: (data: CurlLogData) => void
+	redactHeader?: (name: string, value: string) => string | null
+	redactQueryParam?: (name: string, value: string) => string | null
+	skip?: (data: CurlLogData) => boolean
+}
+
+const DEFAULT_BODY_CONTENT_TYPES = [
+	"application/json",
+	"application/x-www-form-urlencoded",
+	"application/xml",
+	"text/",
+]
+
+const DEFAULT_MAX_BODY_BYTES = 16_384
+
+function shellEscape(value: string): string {
+	return value.replace(/'/g, "'\\''")
+}
+
+function defaultLog(data: CurlLogData): void {
+	console.log(data.curl)
+}
+
+function shouldIncludeBody(contentType: string | null, allowContentTypes: string[]): boolean {
+	if (contentType === null || contentType.length === 0) return false
+	return allowContentTypes.some((allowed) => contentType.startsWith(allowed))
+}
+
+function redactUrl(url: URL, redactQueryParam?: (name: string, value: string) => string | null): string {
+	if (redactQueryParam === undefined || url.search.length === 0) return url.toString()
+
+	const redacted = new URL(url.toString())
+	redacted.search = ""
+
+	for (const [name, value] of url.searchParams.entries()) {
+		const nextValue = redactQueryParam(name, value)
+		if (nextValue === null) continue
+		redacted.searchParams.append(name, nextValue)
+	}
+
+	return redacted.toString()
+}
+
+async function readBodyWithinLimit(request: Request, maxBytes: number): Promise<{
+	body: string | null
+	omittedReason: BodyOmittedReason | null
+}> {
+	if (request.body === null) {
+		return { body: null, omittedReason: "missing" }
+	}
+
+	const contentLength = request.headers.get("content-length")
+	if (contentLength !== null) {
+		const parsedLength = Number.parseInt(contentLength, 10)
+		if (!Number.isNaN(parsedLength) && parsedLength > maxBytes) {
+			return { body: null, omittedReason: "too-large" }
+		}
+	}
+
+	const clone = request.clone()
+	if (clone.body === null) {
+		return { body: null, omittedReason: "missing" }
+	}
+
+	const reader = clone.body.getReader()
+	const chunks: Uint8Array[] = []
+	let totalBytes = 0
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read()
+			if (done) break
+			totalBytes += value.byteLength
+			if (totalBytes > maxBytes) {
+				await reader.cancel()
+				return { body: null, omittedReason: "too-large" }
+			}
+			chunks.push(value)
+		}
+	} catch {
+		return { body: null, omittedReason: "read-error" }
+	}
+
+	const bytes = new Uint8Array(totalBytes)
+	let offset = 0
+
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+
+	return {
+		body: new TextDecoder().decode(bytes),
+		omittedReason: null,
+	}
+}
+
+async function buildCurlLogData(
+	request: Request,
+	options?: Pick<CurlLoggerOptions, "body" | "redactHeader" | "redactQueryParam">,
+): Promise<Pick<CurlLogData, "bodyIncluded" | "bodyOmittedReason" | "curl">> {
+	const parts: string[] = [`curl -X ${request.method}`]
+
+	for (const [name, value] of request.headers.entries()) {
+		const redactedValue = options?.redactHeader !== undefined
+			? options.redactHeader(name, value)
+			: value
+		if (redactedValue === null) continue
+		parts.push(`-H '${shellEscape(name)}: ${shellEscape(redactedValue)}'`)
+	}
+
+	let bodyIncluded = false
+	let bodyOmittedReason: BodyOmittedReason | null = null
+
+	if (options?.body === true || typeof options?.body === "object") {
+		const bodyOptions = typeof options.body === "object" ? options.body : {}
+		const allowContentTypes = bodyOptions.allowContentTypes ?? DEFAULT_BODY_CONTENT_TYPES
+		const contentType = request.headers.get("content-type")
+
+		if (shouldIncludeBody(contentType, allowContentTypes) === false) {
+			bodyOmittedReason = request.body === null ? "missing" : "content-type"
+		} else {
+			const result = await readBodyWithinLimit(
+				request,
+				bodyOptions.maxBytes ?? DEFAULT_MAX_BODY_BYTES,
+			)
+
+			if (result.body === null) {
+				bodyOmittedReason = result.omittedReason
+			} else {
+				bodyIncluded = true
+				parts.push(`--data-raw '${shellEscape(result.body)}'`)
+			}
+		}
+	} else {
+		bodyOmittedReason = "disabled"
+	}
+
+	parts.push(`'${shellEscape(redactUrl(new URL(request.url), options?.redactQueryParam))}'`)
+
+	return {
+		bodyIncluded,
+		bodyOmittedReason,
+		curl: parts.join(" "),
+	}
+}
+
+function curlLogger(
+	options?: CurlLoggerOptions,
+): MiddlewareFn<{ path: string, req: Request }, {}> {
+	const log = options?.log ?? defaultLog
+	const skip = options?.skip
+
+	return async (ctx, next) => {
+		const start = performance.now()
+		const method = ctx.req.method
+		const path = ctx.path
+		const rid = (ctx as Record<string, unknown>)["requestId"] as string | null ?? null
+		const curlDataPromise = buildCurlLogData(ctx.req, options)
+
+		const response = await next()
+		const duration = performance.now() - start
+		const curlData = await curlDataPromise
+
+		const data: CurlLogData = {
+			...curlData,
+			duration,
+			method,
+			path,
+			requestId: rid,
+			status: response.status,
+		}
+
+		if (skip?.(data)) {
+			return response
+		}
+
+		if (options?.instance) {
+			options.instance.info(
+				{
+					bodyIncluded: data.bodyIncluded,
+					bodyOmittedReason: data.bodyOmittedReason,
+					curl: data.curl,
+					duration: data.duration,
+					method: data.method,
+					path: data.path,
+					requestId: data.requestId,
+					status: data.status,
+				},
+				"request curl",
+			)
+		} else {
+			log(data)
+		}
+
+		return response
+	}
+}
+
+export { buildCurlLogData, curlLogger }
+export type {
+	BodyOmittedReason,
+	CurlLogData,
+	CurlLoggerBodyOptions,
+	CurlLoggerOptions,
+}

package/src/detect-runtime.ts

@@ -0,0 +1,19 @@
+export type ServeRuntime = "bun" | "cloudflare" | "deno" | "node"
+
+type DetectGlobal = {
+	Bun?: unknown
+	Deno?: unknown
+	navigator?: { userAgent?: string }
+	process?: { versions?: { node?: string } }
+}
+
+export function detectRuntime(g: DetectGlobal = globalThis): ServeRuntime {
+	if (typeof g.Bun !== "undefined") return "bun"
+	if (typeof g.Deno !== "undefined") return "deno"
+	const ua = g.navigator?.userAgent ?? ""
+	if (ua.includes("Cloudflare-Workers") || ua.includes("workerd")) return "cloudflare"
+	if (g.process?.versions?.node) return "node"
+	throw new Error(
+		'Honey.serve() could not detect a runtime. Pass runtime: "bun" | "node" | "deno".',
+	)
+}

package/src/error.ts

@@ -0,0 +1,52 @@
+import type { FieldError, StatusKey } from "./types.ts"
+import { EMPTY_FIELDS, statusKeyToCode } from "./types.ts"
+
+export class HoneyError extends Error {
+	readonly data?: unknown
+	readonly errorKey: string
+	readonly fields: Record<string, FieldError[]>
+	readonly headers?: Record<string, string>
+	readonly status: number
+	readonly statusKey: StatusKey
+	readonly vars?: Record<string, string | number>
+
+	constructor(opts: {
+		cause?: unknown
+		data?: unknown
+		errorKey: string
+		fields?: Record<string, FieldError[]>
+		headers?: Record<string, string>
+		status: StatusKey
+		vars?: Record<string, string | number>
+	}) {
+		super(opts.errorKey, opts.cause !== undefined ? { cause: opts.cause } : undefined)
+		this.data = opts.data
+		this.errorKey = opts.errorKey
+		this.headers = opts.headers
+		this.statusKey = opts.status
+		this.status = statusKeyToCode[opts.status]
+		this.fields = opts.fields ?? EMPTY_FIELDS
+		this.vars = opts.vars
+	}
+
+	static serialize(e: unknown): Record<string, unknown> {
+		if (!(e instanceof Error)) return { message: String(e) }
+
+		const obj: Record<string, unknown> = {
+			message: e.message,
+			name: e.name,
+			stack: e.stack,
+		}
+
+		if (e instanceof HoneyError) {
+			obj["errorKey"] = e.errorKey
+			obj["status"] = e.status
+			obj["statusKey"] = e.statusKey
+			if (Object.keys(e.fields).length > 0) obj["fields"] = e.fields
+		}
+
+		if (e.cause) obj["cause"] = HoneyError.serialize(e.cause)
+
+		return obj
+	}
+}

package/src/errors.ts

@@ -0,0 +1,87 @@
+import { HoneyError } from "./error.ts"
+import type { ExtractICUVars } from "./i18n.ts"
+import type { FieldError, InferOutput, StandardSchemaLike, StatusKey } from "./types.ts"
+
+type ErrorFactoryOpts<TVars> = {
+	cause?: unknown
+	fields?: Record<string, FieldError[]>
+	headers?: Record<string, string>
+	vars?: TVars
+}
+
+type ErrorDefWithSchema = {
+	schema: StandardSchemaLike
+	status: StatusKey
+}
+
+type ErrorDef = ErrorDefWithSchema | StatusKey
+
+export type ErrorMetaEntry = {
+	schema: StandardSchemaLike | null
+	statusKey: StatusKey
+}
+
+/** Per-key meta — keeps schema + statusKey literals for ComputeErrorsByStatus */
+type ErrorMetaForDef<D extends ErrorDef> = D extends ErrorDefWithSchema
+	? { schema: D["schema"]; statusKey: D["status"] }
+	: D extends StatusKey
+		? { schema: null; statusKey: D }
+		: ErrorMetaEntry
+
+export const ERROR_META: unique symbol = Symbol.for("honey.error.meta")
+
+type ErrorFactoryResult<TMap extends Record<string, ErrorDef>, TTranslations extends Record<string, string>> = {
+	[K in keyof TMap]: TMap[K] extends ErrorDefWithSchema
+		? (data: InferOutput<TMap[K]["schema"]>, opts?: { cause?: unknown; headers?: Record<string, string> }) => HoneyError
+		: K extends keyof TTranslations
+			? (opts?: ErrorFactoryOpts<ExtractICUVars<TTranslations[K]>>) => HoneyError
+			: (opts?: ErrorFactoryOpts<Record<string, string | number>>) => HoneyError
+} & {
+	readonly [ERROR_META]: { [K in keyof TMap]: ErrorMetaForDef<TMap[K]> }
+}
+
+export function defineErrors<
+	TMap extends Record<string, ErrorDef>,
+	TTranslations extends Record<string, string> = Record<string, string>,
+>(
+	map: TMap,
+): ErrorFactoryResult<TMap, TTranslations> {
+	const result = Object.create(null) as Record<string, unknown>
+	const meta = Object.create(null) as Record<string, ErrorMetaEntry>
+
+	for (const [key, def] of Object.entries(map)) {
+		if (typeof def === "string") {
+			/* standard error — string status key */
+			meta[key] = { schema: null, statusKey: def }
+			result[key] = (opts?: ErrorFactoryOpts<Record<string, string | number>>) =>
+				new HoneyError({
+					cause: opts?.cause,
+					errorKey: key,
+					fields: opts?.fields,
+					headers: opts?.headers,
+					status: def,
+					vars: opts?.vars,
+				})
+		} else {
+			/* custom schema error — { status, schema } */
+			meta[key] = { schema: def.schema, statusKey: def.status }
+			result[key] = (data: unknown, opts?: { cause?: unknown; headers?: Record<string, string> }) =>
+				new HoneyError({
+					cause: opts?.cause,
+					data,
+					errorKey: key,
+					headers: opts?.headers,
+					status: def.status,
+				})
+		}
+	}
+
+	Object.defineProperty(result, ERROR_META, {
+		configurable: false,
+		enumerable: false,
+		value: meta,
+		writable: false,
+	})
+
+	return result as ErrorFactoryResult<TMap, TTranslations>
+}

package/src/etag.ts

@@ -0,0 +1,74 @@
+import { replaceResponse } from "./honey-response.ts"
+import type { MiddlewareFn } from "./middleware.ts"
+
+type ETagOptions = {
+	weak?: boolean
+}
+
+/**
+ * FNV-1a 32-bit hash — fast, non-cryptographic, deterministic.
+ * Good enough for ETag fingerprinting (not security-critical).
+ */
+function fnv1a(data: Uint8Array): string {
+	let hash = 0x811c9dc5
+	for (let i = 0; i < data.length; i++) {
+		hash ^= data[i]
+		hash = Math.imul(hash, 0x01000193)
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0")
+}
+
+export function etag(options?: ETagOptions): MiddlewareFn<{ req: Request }, {}> {
+	const weak = options?.weak !== false
+
+	const mw: MiddlewareFn<{ req: Request }, {}> = async (ctx, next) => {
+		const method = ctx.req.method
+		if (method !== "GET" && method !== "HEAD") {
+			return next()
+		}
+
+		const response = await next()
+
+		/* skip error responses — caching errors is wasteful and misleading */
+		if (response.status >= 400) return response
+
+		/* skip streaming responses — can't hash without buffering entire stream */
+		if (
+			response.headers.get("transfer-encoding") === "chunked" ||
+			(response.body !== null &&
+				!response.headers.has("content-length") &&
+				!response.headers.has("content-type"))
+		) {
+			return response
+		}
+
+		/* read body to compute hash */
+		const body = await response.arrayBuffer()
+		if (body.byteLength === 0) return response
+
+		const hash = fnv1a(new Uint8Array(body))
+		const etagValue = weak ? `W/"${hash}"` : `"${hash}"`
+
+		const headers = new Headers(response.headers)
+		headers.set("etag", etagValue)
+
+		/* check If-None-Match — supports comma-separated list and wildcard per RFC 7232 */
+		const ifNoneMatch = ctx.req.headers.get("if-none-match")
+		if (ifNoneMatch === "*" || ifNoneMatch?.split(",").some((v) => v.trim() === etagValue)) {
+			return replaceResponse(response, {
+				body: null,
+				headers,
+				status: 304,
+			})
+		}
+
+		/* return response with ETag header and reconstituted body */
+		return replaceResponse(response, {
+			body,
+			headers,
+			status: response.status,
+		})
+	}
+
+	return mw
+}

package/src/feature-load.ts

@@ -0,0 +1,23 @@
+import { getI18nRuntime } from "./i18n-slot.ts"
+import { getOpenApiRuntime } from "./openapi/spec-factory.ts"
+import { getServeRuntime } from "./serve-slot.ts"
+
+function isReady(name: "i18n" | "openapi" | "serve"): boolean {
+	try {
+		if (name === "i18n") getI18nRuntime()
+		else if (name === "openapi") getOpenApiRuntime()
+		else getServeRuntime()
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Opaque so bun/esbuild do not follow unused feature entries into a fetch-only bundle. */
+export async function loadHoneyFeature(name: "i18n" | "openapi" | "serve"): Promise<void> {
+	if (isReady(name)) return
+	const mod = (await import(["@lovrozagar/honey", name].join("/"))) as Record<string, unknown>
+	const enable = { i18n: "enableI18n", openapi: "enableOpenApi", serve: "enableServe" }[name]
+	const fn = mod[enable]
+	if (typeof fn === "function") fn()
+}