@lovrozagar/honey 0.1.0

package/src/node-request.ts

@@ -0,0 +1,240 @@
+import type { IncomingMessage } from "node:http"
+import { Readable } from "node:stream"
+import { NODE_OUTBOUND } from "./honey-response.ts"
+
+/** bodyLimit uses this to swap the inbound stream without `new Request(req)`. */
+export const REPLACE_BODY = Symbol.for("honey.replaceBody")
+
+/**
+ * Headers view over IncomingMessage. `get`/`has` read Node's already-parsed
+ * map. A real `Headers` is built only if something iterates or mutates.
+ */
+export class NodeHeaders {
+	#incoming: IncomingMessage
+	#native: Headers | null = null
+
+	constructor(incoming: IncomingMessage) {
+		this.#incoming = incoming
+	}
+
+	append(name: string, value: string): void {
+		this.#ensureNative().append(name, value)
+	}
+
+	delete(name: string): void {
+		this.#ensureNative().delete(name)
+	}
+
+	get(name: string): string | null {
+		if (this.#native) return this.#native.get(name)
+		const raw = this.#incoming.headers[name.toLowerCase()]
+		if (raw === undefined) return null
+		return Array.isArray(raw) ? raw.join(", ") : raw
+	}
+
+	getSetCookie(): string[] {
+		return this.#ensureNative().getSetCookie()
+	}
+
+	has(name: string): boolean {
+		if (this.#native) return this.#native.has(name)
+		return this.#incoming.headers[name.toLowerCase()] !== undefined
+	}
+
+	set(name: string, value: string): void {
+		this.#ensureNative().set(name, value)
+	}
+
+	forEach(callback: (value: string, key: string, parent: Headers) => void, thisArg?: unknown): void {
+		this.#ensureNative().forEach(callback, thisArg)
+	}
+
+	keys(): IterableIterator<string> {
+		return this.#ensureNative().keys()
+	}
+
+	values(): IterableIterator<string> {
+		return this.#ensureNative().values()
+	}
+
+	entries(): IterableIterator<[string, string]> {
+		return this.#ensureNative().entries()
+	}
+
+	[Symbol.iterator](): IterableIterator<[string, string]> {
+		return this.#ensureNative()[Symbol.iterator]()
+	}
+
+	get [Symbol.toStringTag](): string {
+		return "Headers"
+	}
+
+	#ensureNative(): Headers {
+		if (this.#native) return this.#native
+		const headers = new Headers()
+		const raw = this.#incoming.rawHeaders
+		for (let i = 0; i < raw.length; i += 2) {
+			const name = raw[i]
+			if (name.charCodeAt(0) === 58) continue
+			headers.append(name, raw[i + 1])
+		}
+		this.#native = headers
+		return headers
+	}
+}
+
+/**
+ * Request-shaped wrapper around IncomingMessage. Avoids `new Request()`
+ * until a body method needs the real Fetch object (formData / blob / clone).
+ */
+export class NodeRequest {
+	readonly [NODE_OUTBOUND] = true
+	readonly cache = "default" as RequestCache
+	readonly credentials = "same-origin" as RequestCredentials
+	readonly destination = "" as RequestDestination
+	readonly headers: NodeHeaders
+	readonly integrity = ""
+	readonly keepalive = false
+	readonly method: string
+	readonly mode = "cors" as RequestMode
+	readonly redirect = "follow" as RequestRedirect
+	readonly referrer = "about:client"
+	readonly referrerPolicy = "" as ReferrerPolicy
+	readonly url: string
+
+	#incoming: IncomingMessage
+	#hasBody: boolean
+	#webBody: ReadableStream<Uint8Array> | null | undefined
+	#bodyUsed = false
+	#fetch: Request | null = null
+	#signal: AbortSignal | null = null
+
+	constructor(incoming: IncomingMessage) {
+		this.#incoming = incoming
+		const host = incoming.headers.host ?? "localhost"
+		this.url = `http://${host}${incoming.url ?? "/"}`
+		this.method = (incoming.method ?? "GET").toUpperCase()
+		this.headers = new NodeHeaders(incoming)
+		this.#hasBody = this.method !== "GET" && this.method !== "HEAD"
+	}
+
+	get body(): ReadableStream<Uint8Array> | null {
+		if (!this.#hasBody) return null
+		if (this.#webBody === undefined) {
+			this.#webBody = Readable.toWeb(this.#incoming) as ReadableStream<Uint8Array>
+		}
+		return this.#webBody
+	}
+
+	get bodyUsed(): boolean {
+		return this.#bodyUsed || this.#incoming.readableEnded
+	}
+
+	get signal(): AbortSignal {
+		if (this.#signal) return this.#signal
+		const ac = new AbortController()
+		this.#incoming.once("aborted", () => ac.abort())
+		this.#signal = ac.signal
+		return this.#signal
+	}
+
+	get duplex(): "half" {
+		return "half"
+	}
+
+	[REPLACE_BODY](stream: ReadableStream<Uint8Array>): void {
+		this.#webBody = stream
+		this.#hasBody = true
+		this.#fetch = null
+	}
+
+	async arrayBuffer(): Promise<ArrayBuffer> {
+		const buf = await this.#readIncoming()
+		return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer
+	}
+
+	async blob(): Promise<Blob> {
+		return this.#asFetch().blob()
+	}
+
+	async bytes(): Promise<Uint8Array> {
+		const buf = await this.#readIncoming()
+		return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+	}
+
+	clone(): Request {
+		return this.#asFetch().clone()
+	}
+
+	async formData(): Promise<FormData> {
+		return this.#asFetch().formData()
+	}
+
+	async json(): Promise<unknown> {
+		const text = await this.text()
+		return text.length === 0 ? null : JSON.parse(text)
+	}
+
+	async text(): Promise<string> {
+		const buf = await this.#readIncoming()
+		return buf.toString("utf8")
+	}
+
+	#asFetch(): Request {
+		if (this.#fetch) return this.#fetch
+		this.#fetch = new Request(this.url, {
+			body: this.body,
+			duplex: this.#hasBody ? "half" : undefined,
+			headers: this.#incoming.headers as HeadersInit,
+			method: this.method,
+			signal: this.signal,
+		} as RequestInit)
+		this.#bodyUsed = true
+		return this.#fetch
+	}
+
+	async #readIncoming(): Promise<Buffer> {
+		this.#bodyUsed = true
+		if (!this.#hasBody) return Buffer.alloc(0)
+		if (this.#fetch) return Buffer.from(await this.#fetch.arrayBuffer())
+		if (this.#webBody) return streamToBuffer(this.#webBody)
+		const chunks: Buffer[] = []
+		for await (const chunk of this.#incoming) {
+			chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk)
+		}
+		return chunks.length === 1 ? chunks[0] : Buffer.concat(chunks)
+	}
+}
+
+async function streamToBuffer(stream: ReadableStream<Uint8Array>): Promise<Buffer> {
+	const reader = stream.getReader()
+	const chunks: Buffer[] = []
+	while (true) {
+		const { done, value } = await reader.read()
+		if (done) break
+		chunks.push(Buffer.from(value))
+	}
+	return chunks.length === 1 ? chunks[0] : Buffer.concat(chunks)
+}
+
+const REQUEST_HAS_INSTANCE = Symbol.for("honey.requestHasInstance")
+
+function installRequestHasInstance(): void {
+	const ctor = Request as typeof Request & { [REQUEST_HAS_INSTANCE]?: boolean }
+	if (ctor[REQUEST_HAS_INSTANCE]) return
+	const original = Request[Symbol.hasInstance]
+	Object.defineProperty(Request, Symbol.hasInstance, {
+		configurable: true,
+		value(this: Function, value: unknown) {
+			if (this === Request && value instanceof NodeRequest) return true
+			return original.call(this, value)
+		},
+	})
+	ctor[REQUEST_HAS_INSTANCE] = true
+}
+
+installRequestHasInstance()
+
+export function incomingToNodeRequest(req: IncomingMessage): Request {
+	return new NodeRequest(req) as unknown as Request
+}

package/src/node.ts

@@ -0,0 +1,212 @@
+import type { IncomingMessage, Server, ServerResponse } from "node:http"
+import { createServer } from "node:http"
+import { Readable, type Duplex } from "node:stream"
+import { pipeline } from "node:stream/promises"
+import type { Honey } from "./index.ts"
+import { isHoneyResponse } from "./honey-response.ts"
+import { incomingToNodeRequest } from "./node-request.ts"
+
+type ServeOptions<TEnv> = {
+	env: TEnv
+	hostname?: string
+	port?: number
+}
+
+/** Buffer known-size bodies up to this many bytes, then `res.end(buf)`. */
+const BUFFER_BODY_MAX = 256 * 1024
+const RAW_BODY = Symbol.for("honey.rawBody")
+
+function incomingToRequest(req: IncomingMessage): Request {
+	return incomingToNodeRequest(req)
+}
+
+function collectNodeHeaders(
+	response: Response,
+	extra?: Record<string, string>,
+): Record<string, string | string[]> {
+	const headerObj: Record<string, string | string[]> = {}
+	let hasSetCookie = false
+	response.headers.forEach((value, key) => {
+		if (key === "set-cookie") {
+			hasSetCookie = true
+			return
+		}
+		headerObj[key] = value
+	})
+	if (hasSetCookie) {
+		const setCookies = response.headers.getSetCookie()
+		if (setCookies.length > 0) headerObj["set-cookie"] = setCookies
+	}
+	if (extra) Object.assign(headerObj, extra)
+	return headerObj
+}
+
+function shouldBufferBody(response: Response): boolean {
+	const rawLen = response.headers.get("content-length")
+	if (rawLen !== null) {
+		const len = Number(rawLen)
+		return Number.isFinite(len) && len <= BUFFER_BODY_MAX
+	}
+	const ct = response.headers.get("content-type") ?? ""
+	if (ct.startsWith("text/event-stream")) return false
+	return (
+		ct.startsWith("application/json") ||
+		ct.startsWith("text/plain") ||
+		ct.startsWith("text/html") ||
+		ct.startsWith("text/csv") ||
+		ct.startsWith("application/xml")
+	)
+}
+
+function rawBodyOf(response: Response): string | Uint8Array | undefined {
+	return (response as Response & { [RAW_BODY]?: string | Uint8Array })[RAW_BODY]
+}
+
+async function responseToNode(response: Response, res: ServerResponse): Promise<void> {
+	if (isHoneyResponse(response)) {
+		const raw = response.rawBody
+		if (typeof raw === "string" || raw instanceof Uint8Array) {
+			const byteLength = typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength
+			res.writeHead(response.status, { ...response.plainHeaders, "content-length": String(byteLength) })
+			res.end(raw)
+			return
+		}
+		const stream = response.body
+		if (stream === null) {
+			res.writeHead(response.status, response.plainHeaders)
+			res.end()
+			return
+		}
+		res.writeHead(response.status, response.plainHeaders)
+		try {
+			await pipeline(Readable.fromWeb(stream as import("node:stream/web").ReadableStream), res)
+		} catch {
+			if (!res.destroyed) res.destroy()
+		}
+		return
+	}
+
+	const raw = rawBodyOf(response)
+	if (typeof raw === "string" || raw instanceof Uint8Array) {
+		const byteLength = typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength
+		res.writeHead(response.status, collectNodeHeaders(response, { "content-length": String(byteLength) }))
+		res.end(raw)
+		return
+	}
+
+	const body = response.body
+	if (body === null) {
+		res.writeHead(response.status, collectNodeHeaders(response))
+		res.end()
+		return
+	}
+
+	if (shouldBufferBody(response)) {
+		const buf = Buffer.from(await response.arrayBuffer())
+		if (res.destroyed) return
+		res.writeHead(
+			response.status,
+			collectNodeHeaders(response, { "content-length": String(buf.byteLength) }),
+		)
+		res.end(buf)
+		return
+	}
+
+	res.writeHead(response.status, collectNodeHeaders(response))
+	try {
+		await pipeline(Readable.fromWeb(body as import("node:stream/web").ReadableStream), res)
+	} catch {
+		if (!res.destroyed) res.destroy()
+	}
+}
+
+export type HoneyServer = Server & {
+	shutdown(timeout?: number): Promise<void>
+}
+
+export function serve<TEnv>(
+	app: Honey<TEnv, unknown, unknown, unknown, unknown, string, string>,
+	options: ServeOptions<TEnv>,
+): HoneyServer {
+	const env = options.env
+	let inflight = 0
+	let draining = false
+	let drainResolve: (() => void) | null = null
+
+	const server = createServer(async (req, res) => {
+		if (draining) {
+			res.writeHead(503)
+			res.end("Service Unavailable")
+			return
+		}
+		inflight++
+		try {
+			const request = incomingToRequest(req)
+			const maybe = app.fetch(request, env)
+			const response = maybe instanceof Promise ? await maybe : maybe
+			await responseToNode(response, res)
+		} catch {
+			if (!res.headersSent) {
+				res.writeHead(500)
+				res.end("Internal Server Error")
+			} else if (!res.destroyed) {
+				res.destroy()
+			}
+		} finally {
+			inflight--
+			if (draining && inflight === 0) {
+				drainResolve?.()
+			}
+		}
+	})
+
+	/* WebSocket upgrade handling */
+	server.on("upgrade", async (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+		try {
+			const request = incomingToRequest(req)
+			const envWithUpgrade = { ...env, __nodeUpgrade: { head, req, socket } } as TEnv
+			const maybe = app.fetch(request, envWithUpgrade)
+			const response = maybe instanceof Promise ? await maybe : maybe
+
+			if (response.status !== 101) {
+				const text = await response.text()
+				socket.write(
+					`HTTP/1.1 ${response.status} ${response.statusText ?? "Error"}\r\n` +
+						"content-type: application/json\r\n" +
+						`\r\n${text}`,
+				)
+				socket.destroy()
+			}
+		} catch {
+			socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n")
+			socket.destroy()
+		}
+	})
+
+	server.listen(options?.port ?? 0, options?.hostname)
+
+	const honeyServer = server as HoneyServer
+	honeyServer.shutdown = (timeout?: number): Promise<void> => {
+		draining = true
+
+		return new Promise<void>((resolve) => {
+			server.close(() => {
+				if (inflight === 0) {
+					resolve()
+					return
+				}
+				drainResolve = resolve
+			})
+
+			if (timeout !== undefined) {
+				setTimeout(() => {
+					drainResolve = null
+					server.closeAllConnections()
+					resolve()
+				}, timeout)
+			}
+		})
+	}
+
+	return honeyServer
+}

package/src/openapi/register.ts

@@ -0,0 +1,19 @@
+import { generateManifest, generateOpenApi } from "../codegen.ts"
+import { toYaml } from "../yaml.ts"
+import { scalar } from "./scalar.ts"
+import { swagger } from "./swagger.ts"
+import { registerOpenApiRuntime } from "./spec-factory.ts"
+
+export function enableOpenApi(): void {
+	registerOpenApiRuntime({
+		docsUi: (kind, specUrl) =>
+			kind === "swagger" ? swagger({ url: specUrl }) : scalar({ url: specUrl }),
+		generateManifest: (app) => Promise.resolve(generateManifest(app as never)),
+		generateOpenApi: (app, options) => generateOpenApi(app as never, options),
+		toYaml,
+	})
+}
+
+enableOpenApi()
+
+export { spec } from "./spec.ts"

package/src/openapi/scalar.ts

@@ -0,0 +1,33 @@
+import type { TypedResponse } from "../response.ts"
+
+type ScalarOptions = {
+  url: string
+  [key: string]: unknown
+}
+
+export function scalar(
+  options: ScalarOptions,
+): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
+  const { url, ...rest } = options
+  const config = JSON.stringify({ url, ...rest })
+
+  const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>API Reference</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  <script>
+    Scalar.createApiReference(document.getElementById("app"), ${config})
+  </script>
+</body>
+</html>`
+
+  const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
+  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+  return handler
+}

package/src/openapi/spec-factory.ts

@@ -0,0 +1,46 @@
+/** Slot for runtime spec/manifest generation. Filled by `import "@lovrozagar/honey/openapi"`. */
+
+export type OpenApiGenerate = (
+	app: unknown,
+	options: {
+		filterRoutes?: (route: { meta: unknown; method: string; path: string }) => boolean
+		info: { description?: string; title: string; version: string }
+		securitySchemes?: Record<string, unknown>
+	},
+) => Promise<unknown>
+
+export type ManifestGenerate = (app: unknown) => Promise<unknown>
+
+export type YamlGenerate = (value: unknown) => string
+
+import type { HoneyRes } from "../response.ts"
+
+export type DocsUi = (
+	kind: "scalar" | "swagger",
+	specUrl: string,
+) => (ctx: { res: HoneyRes }) => Response | Promise<Response>
+
+export type OpenApiRuntime = {
+	docsUi: DocsUi
+	generateManifest: ManifestGenerate
+	generateOpenApi: OpenApiGenerate
+	toYaml: YamlGenerate
+}
+
+const MISSING =
+	'Runtime OpenAPI/manifest generation requires `import "@lovrozagar/honey/openapi"` in the app entry.'
+
+let runtime: OpenApiRuntime | undefined
+
+export function registerOpenApiRuntime(next: OpenApiRuntime): void {
+	runtime = next
+}
+
+export function resetOpenApiRuntime(): void {
+	runtime = undefined
+}
+
+export function getOpenApiRuntime(): OpenApiRuntime {
+	if (!runtime) throw new Error(MISSING)
+	return runtime
+}

package/src/openapi/spec.ts

@@ -0,0 +1,31 @@
+import { generateOpenApi } from "../codegen.ts"
+import type { OpenApiRouteInfo } from "../codegen.ts"
+import type { DefaultMeta } from "../types.ts"
+import type { TypedResponse } from "../response.ts"
+
+type SpecOptions<TMeta = Record<string, unknown> | null> = {
+  description?: string
+  filterRoutes?: (route: OpenApiRouteInfo<DefaultMeta & TMeta>) => boolean
+  securitySchemes?: Record<string, unknown>
+  title: string
+  version: string
+}
+
+export function spec<TMeta = Record<string, unknown> | null>(
+  options: SpecOptions<TMeta>,
+): (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => TypedResponse | Promise<TypedResponse> {
+  let cached: string | null = null
+
+  const handler = async (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => {
+    if (cached === null) {
+      const desc = Object.getOwnPropertyDescriptor(handler, Symbol.for("honey.app"))
+      const openApiSpec = desc
+        ? await generateOpenApi(desc.value, { filterRoutes: options.filterRoutes, info: options, securitySchemes: options.securitySchemes })
+        : {}
+      cached = JSON.stringify(openApiSpec)
+    }
+    return ctx.res.json("ok", JSON.parse(cached))
+  }
+  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+  return handler
+}

package/src/openapi/swagger.ts

@@ -0,0 +1,34 @@
+import type { TypedResponse } from "../response.ts"
+
+type SwaggerOptions = {
+  url: string
+  [key: string]: unknown
+}
+
+export function swagger(
+  options: SwaggerOptions,
+): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
+  const { url, ...rest } = options
+  const config = JSON.stringify({ dom_id: "#swagger-ui", url, ...rest })
+
+  const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Swagger UI</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle(${config})
+  </script>
+</body>
+</html>`
+
+  const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
+  Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+  return handler
+}