@lovrozagar/honey 0.1.0

package/src/powered-by.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareFn } from "./middleware.ts"
+
+type PoweredByOptions = {
+	name?: string
+}
+
+export function poweredBy(options?: PoweredByOptions): MiddlewareFn<{}, {}> {
+	const name = options?.name ?? "Honey"
+
+	const mw: MiddlewareFn<{}, {}> = async (_ctx, next) => {
+		const response = await next()
+		response.headers.set("x-powered-by", name)
+		return response
+	}
+
+	return mw
+}

package/src/pretty-json.ts

@@ -0,0 +1,39 @@
+import { replaceResponse } from "./honey-response.ts"
+import type { MiddlewareFn } from "./middleware.ts"
+
+type PrettyJsonOptions = {
+	query?: string
+	space?: number
+}
+
+export function prettyJson(options?: PrettyJsonOptions): MiddlewareFn<{ req: Request }, {}> {
+	const query = options?.query ?? "pretty"
+	const space = options?.space ?? 2
+
+	const mw: MiddlewareFn<{ req: Request }, {}> = async (ctx, next) => {
+		const url = ctx.req.url
+		const qIdx = url.indexOf("?")
+		if (qIdx === -1 || !url.includes(query, qIdx)) {
+			return next()
+		}
+
+		const response = await next()
+
+		const contentType = response.headers.get("content-type")
+		if (!contentType || !contentType.includes("application/json")) {
+			return response
+		}
+
+		const text = await response.text()
+		const parsed: unknown = JSON.parse(text)
+		const formatted = JSON.stringify(parsed, null, space)
+
+		return replaceResponse(response, {
+			body: formatted,
+			headers: response.headers,
+			status: response.status,
+		})
+	}
+
+	return mw
+}

package/src/proxy.ts

@@ -0,0 +1,155 @@
+import { HoneyError } from "./error.ts"
+import { EK, SK } from "./types.ts"
+
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"])
+
+/**
+ * Proxy configuration — controls how requests are forwarded to downstream services.
+ *
+ * `destination` is the only required field. Framework builds the RequestInit
+ * (headers, body, signal, redirect) and passes it along with the resolved URL.
+ */
+export type ProxyConfig<TCtx> = {
+	/**
+	 * Where to send the request. Framework doesn't care how — CF service binding,
+	 * URL fetch, Durable Object stub, anything that returns a Response.
+	 *
+	 * @param ctx - honey context (middleware additions available)
+	 * @param url - path + query string, after rewriteUrl if provided
+	 * @param init - framework-prepared RequestInit (method, headers, body, signal, redirect)
+	 */
+	destination: (ctx: TCtx, url: string, init: RequestInit) => Response | Promise<Response>
+
+	/**
+	 * Hook after downstream responds, before returning to client.
+	 * Return void to passthrough, or return a new Response to replace.
+	 * Can mutate response.headers in place (zero allocation).
+	 * NOT called for 101 WebSocket upgrades (opaque response).
+	 */
+	onResponse?: (ctx: TCtx, response: Response) => void | Response | Promise<void | Response>
+
+	/**
+	 * Set request headers before forwarding. Called after hop-by-hop headers are stripped.
+	 * Static record: entries are set on the headers object.
+	 * Function: mutate headers in place.
+	 */
+	requestHeaders?: Record<string, string> | ((ctx: TCtx, headers: Headers) => void)
+
+	/**
+	 * Rewrite URL before passing to destination.
+	 * Receives path + query string, returns transformed URL.
+	 */
+	rewriteUrl?: (url: string, ctx: TCtx) => string
+
+	/**
+	 * Timeout in milliseconds. Default: 30000.
+	 * Accepts a number or a function that receives ctx and returns a number.
+	 * Disabled for WebSocket upgrades.
+	 */
+	timeout?: number | ((ctx: TCtx) => number)
+}
+
+/**
+ * Creates a proxy handler function from config.
+ * Used internally by RouteBuilder.proxy() — not meant for direct consumption.
+ *
+ * TCtx is unconstrained because HandlerCtx uses Omit which breaks structural
+ * compatibility with { path, req }. At runtime ctx is always HoneyContext
+ * which has both fields — we access them via property access on the object.
+ */
+export function createProxyHandler<TCtx>(
+	config: ProxyConfig<TCtx>,
+): (ctx: TCtx) => Promise<Response> {
+	const timeoutOpt = config.timeout ?? 30_000
+
+	return async (ctx: TCtx) => {
+		const timeoutMs = typeof timeoutOpt === "function" ? timeoutOpt(ctx) : timeoutOpt
+		/* HoneyContext always has path + req — safe at runtime */
+		const c = ctx as Record<string, unknown>
+		const request = c["req"] as Request
+		const method = request.method
+		const isWs = request.headers.get("upgrade") === "websocket"
+
+		/* URL resolution — path + query, no new URL() */
+		const rawUrl = request.url
+		const protoEnd = rawUrl.indexOf("//")
+		const pathStart = protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2)
+		const qIdx = pathStart === -1 ? -1 : rawUrl.indexOf("?", pathStart)
+		const pathOnly = c["path"] as string
+		const rawPathQuery = qIdx === -1 ? pathOnly : pathOnly + rawUrl.substring(qIdx)
+		const url = config.rewriteUrl ? config.rewriteUrl(rawPathQuery, ctx) : rawPathQuery
+
+		/* headers — one copy (original is immutable), strip hop-by-hop */
+		const headers = new Headers(request.headers)
+		headers.delete("connection")
+		headers.delete("keep-alive")
+		headers.delete("transfer-encoding")
+		headers.delete("te")
+		headers.delete("trailer")
+		headers.delete("proxy-authenticate")
+		headers.delete("proxy-authorization")
+
+		if (isWs) {
+			headers.set("connection", "upgrade")
+		}
+
+		if (config.requestHeaders) {
+			if (typeof config.requestHeaders === "function") {
+				config.requestHeaders(ctx, headers)
+			} else {
+				for (const [k, v] of Object.entries(config.requestHeaders)) {
+					headers.set(k, v)
+				}
+			}
+		}
+
+		/* build init — plain object, no new Request() */
+		const hasBody = BODY_METHODS.has(method)
+		const init: RequestInit = {
+			body: hasBody ? request.body : undefined,
+			headers,
+			method,
+			redirect: "manual",
+			signal: isWs ? undefined : AbortSignal.timeout(timeoutMs),
+		}
+
+		/* duplex required for streaming body (Node needs it, CF handles implicitly) */
+		if (hasBody && request.body) {
+			;(init as Record<string, unknown>)["duplex"] = "half"
+		}
+
+		/* forward */
+		let response: Response
+		try {
+			response = await config.destination(ctx, url, init)
+		} catch (error) {
+			if (error instanceof DOMException && error.name === "TimeoutError") {
+				throw new HoneyError({
+					errorKey: EK.gateway_timeout,
+					status: SK.gateway_timeout,
+				})
+			}
+			if (error instanceof TypeError) {
+				throw new HoneyError({
+					errorKey: EK.bad_gateway,
+					status: SK.bad_gateway,
+				})
+			}
+			throw error
+		}
+
+		/* WS 101 — return immediately, opaque */
+		if (response.status === 101) {
+			return response
+		}
+
+		/* response hook */
+		if (config.onResponse) {
+			const replaced = await config.onResponse(ctx, response)
+			if (replaced) return replaced
+		}
+
+		/* stream through — zero wrapping */
+		return response
+	}
+}

package/src/python-type-emitter.ts

@@ -0,0 +1,144 @@
+import { schemaToIR } from "./codegen-ir.ts"
+import type { IRField, IRSchema } from "./codegen-ir.ts"
+
+const PY_RESERVED = new Set([
+	"False", "None", "True", "and", "as", "assert", "async", "await",
+	"break", "class", "continue", "def", "del", "elif", "else", "except",
+	"finally", "for", "from", "global", "if", "import", "in", "is",
+	"lambda", "nonlocal", "not", "or", "pass", "raise", "return", "try",
+	"while", "with", "yield",
+])
+
+/** Suffix reserved words with `_` per PEP 8 convention. */
+export function pyIdent(name: string): string {
+	if (PY_RESERVED.has(name)) return `${name}_`
+	return name.replace(/[^a-zA-Z0-9_]/g, "_")
+}
+
+function primitiveToPy(t: string): string {
+	if (t === "string") return "str"
+	if (t === "integer") return "int"
+	if (t === "number") return "float"
+	if (t === "boolean") return "bool"
+	if (t === "null") return "None"
+	return "Any"
+}
+
+function formatConstPy(v: string | number | boolean): string {
+	if (typeof v === "string") return JSON.stringify(v)
+	if (typeof v === "boolean") return v ? "True" : "False"
+	return String(v)
+}
+
+function emitScalarPy(ir: Extract<IRSchema, { kind: "scalar" }>): string {
+	if (ir.enum) {
+		const members = ir.enum
+			.map((v) => (typeof v === "string" ? JSON.stringify(v) : String(v)))
+			.join(", ")
+		return `Literal[${members}]`
+	}
+	return primitiveToPy(ir.type)
+}
+
+function emitObjectPy(ir: Extract<IRSchema, { kind: "object" }>, depth: number): string {
+	const { fields, additional } = ir
+
+	if (fields.length === 0) {
+		if (additional) {
+			return `dict[str, ${irToPython(additional, depth + 1)}]`
+		}
+		return "dict[str, Any]"
+	}
+
+	const sortedFields = fields.slice().sort((a, b) => a.name.localeCompare(b.name))
+	const entries = sortedFields.map((f) => {
+		const pyType = irToPython(f.schema, depth + 1)
+		const annotation = f.required ? pyType : `NotRequired[${pyType}]`
+		return `${JSON.stringify(f.name)}: ${annotation}`
+	})
+
+	return `TypedDict("X", {${entries.join(", ")}})`
+}
+
+/**
+ * Convert an IRSchema to a Python type string.
+ * depth > 8 returns `Any` (mirrors TS `unknown` fallback).
+ */
+export function irToPython(ir: IRSchema, depth = 0): string {
+	if (depth > 8) return "Any"
+
+	switch (ir.kind) {
+		case "scalar":
+			return emitScalarPy(ir)
+
+		case "const":
+			return `Literal[${formatConstPy(ir.value)}]`
+
+		case "object":
+			return emitObjectPy(ir, depth)
+
+		case "array":
+			return `list[${irToPython(ir.items, depth + 1)}]`
+
+		case "tuple":
+			return `tuple[${ir.items.map((i) => irToPython(i, depth + 1)).join(", ")}]`
+
+		case "union": {
+			/* union-of-const → single Literal[...] to match mixed enum behavior */
+			if (ir.variants.length > 0 && ir.variants.every((v) => v.kind === "const")) {
+				const members = ir.variants
+					.map((v) => formatConstPy((v as Extract<IRSchema, { kind: "const" }>).value))
+					.join(", ")
+				return `Literal[${members}]`
+			}
+			return ir.variants.map((v) => irToPython(v, depth + 1)).join(" | ")
+		}
+
+		case "allOf": {
+			const allObjects = ir.parts.every((p) => p.kind === "object")
+			if (!allObjects) return "Any"
+			/* later parts overwrite earlier (mirrors Object.assign semantics in old jsonSchemaToPy) */
+			const mergedMap = new Map<string, IRField>()
+			const requiredSet = new Set<string>()
+			for (const part of ir.parts) {
+				const obj = part as Extract<IRSchema, { kind: "object" }>
+				for (const f of obj.fields) {
+					mergedMap.set(f.name, f)
+					if (f.required) requiredSet.add(f.name)
+				}
+			}
+			const mergedFields: IRField[] = Array.from(mergedMap.values()).map((f) => {
+				const mf: IRField = Object.assign({}, f)
+				mf.required = requiredSet.has(f.name)
+				return mf
+			})
+			return emitObjectPy({ fields: mergedFields, kind: "object" }, depth)
+		}
+
+		case "ref":
+			return ir.name
+
+		case "nullable":
+			return `${irToPython(ir.inner, depth + 1)} | None`
+
+		/*
+		 * binary kind arises from {type:"string", format:"binary"}.
+		 * dominant case matches "str"; bare {format:"binary"} with no type is
+		 * a deliberate 1-case divergence from old jsonSchemaToPy (see spec §binary).
+		 */
+		case "binary":
+			return "str"
+
+		case "unknown":
+			return "Any"
+	}
+}
+
+/** Thin shim — delegates to irToPython(schemaToIR(schema), depth). */
+export function jsonSchemaToPy(
+	schema: Record<string, unknown> | undefined,
+	depth = 0,
+): string {
+	if (!schema || depth > 8) return "Any"
+	return irToPython(schemaToIR(schema), depth)
+}

package/src/realtime/buffer.ts

@@ -0,0 +1,101 @@
+const DEFAULT_SIZE = 100
+const DEFAULT_TTL = 300_000
+
+type BufferEntry = { id: number; data: unknown }
+
+type ConnectionBuffer = {
+	entries: BufferEntry[]
+	head: number
+	count: number
+	nextId: number
+	capacity: number
+	ttlTimer: ReturnType<typeof setTimeout> | null
+}
+
+export class ReconnectBuffer {
+	private readonly size: number
+	private readonly ttl: number
+	private readonly connections = new Map<string, ConnectionBuffer>()
+
+	constructor(opts?: { size?: number; ttl?: number }) {
+		const size = opts?.size ?? DEFAULT_SIZE
+		if (size <= 0) {
+			throw new Error("ReconnectBuffer size must be greater than 0")
+		}
+		this.size = size
+		this.ttl = opts?.ttl ?? DEFAULT_TTL
+	}
+
+	create(existingToken?: string): string {
+		const token = existingToken ?? crypto.randomUUID()
+		this.connections.set(token, {
+			capacity: this.size,
+			count: 0,
+			entries: Array.from<BufferEntry>({ length: this.size }),
+			head: 0,
+			nextId: 1,
+			ttlTimer: null,
+		})
+		return token
+	}
+
+	push(token: string, data: unknown): number {
+		const conn = this.connections.get(token)
+		if (!conn) {
+			throw new Error(`Unknown reconnect token: ${token}`)
+		}
+
+		/* Cancel any pending TTL timer on reconnect */
+		if (conn.ttlTimer !== null) {
+			clearTimeout(conn.ttlTimer)
+			conn.ttlTimer = null
+		}
+
+		const id = conn.nextId++
+		const index = (conn.head + conn.count) % conn.capacity
+
+		if (conn.count < conn.capacity) {
+			conn.entries[index] = { data, id }
+			conn.count++
+		} else {
+			/* Ring is full — overwrite oldest at head, advance head */
+			conn.entries[conn.head] = { data, id }
+			conn.head = (conn.head + 1) % conn.capacity
+		}
+
+		return id
+	}
+
+	replay(token: string, lastId: number): Array<{ id: number; data: unknown }> | null {
+		const conn = this.connections.get(token)
+		if (!conn) return null
+
+		const result: Array<{ id: number; data: unknown }> = []
+		for (let i = 0; i < conn.count; i++) {
+			const entry = conn.entries[(conn.head + i) % conn.capacity]
+			if (entry.id > lastId) {
+				result.push(entry)
+			}
+		}
+		return result
+	}
+
+	disconnect(token: string): void {
+		const conn = this.connections.get(token)
+		if (!conn) return
+
+		conn.ttlTimer = setTimeout(() => {
+			this.connections.delete(token)
+		}, this.ttl)
+	}
+
+	destroy(token: string): void {
+		const conn = this.connections.get(token)
+		if (!conn) return
+
+		if (conn.ttlTimer !== null) {
+			clearTimeout(conn.ttlTimer)
+		}
+		this.connections.delete(token)
+	}
+}

package/src/realtime/bus.ts

@@ -0,0 +1,93 @@
+export interface RealtimeBus {
+	subscribe(connId: string, topic: string): void
+	unsubscribe(connId: string, topic: string): void
+	unsubscribeAll(connId: string): void
+	publish(topic: string, data: unknown): void
+	onMessage(connId: string, handler: (data: unknown) => void): void
+	removeHandler(connId: string): void
+	presence(topic: string): string[]
+}
+
+export function createBus(): RealtimeBus {
+	/* topic -> set of connIds subscribed to it */
+	const topicSubs = new Map<string, Set<string>>()
+	/* connId -> set of topics it is subscribed to (reverse lookup for unsubscribeAll) */
+	const connTopics = new Map<string, Set<string>>()
+	/* connId -> message handler */
+	const handlers = new Map<string, (data: unknown) => void>()
+
+	function subscribe(connId: string, topic: string): void {
+		let subs = topicSubs.get(topic)
+		if (!subs) {
+			subs = new Set()
+			topicSubs.set(topic, subs)
+		}
+		subs.add(connId)
+
+		let topics = connTopics.get(connId)
+		if (!topics) {
+			topics = new Set()
+			connTopics.set(connId, topics)
+		}
+		topics.add(topic)
+	}
+
+	function unsubscribe(connId: string, topic: string): void {
+		const subs = topicSubs.get(topic)
+		if (subs) {
+			subs.delete(connId)
+			if (subs.size === 0) topicSubs.delete(topic)
+		}
+
+		const topics = connTopics.get(connId)
+		if (topics) {
+			topics.delete(topic)
+			if (topics.size === 0) connTopics.delete(connId)
+		}
+	}
+
+	function unsubscribeAll(connId: string): void {
+		const topics = connTopics.get(connId)
+		if (!topics) return
+
+		for (const topic of topics) {
+			const subs = topicSubs.get(topic)
+			if (subs) {
+				subs.delete(connId)
+				if (subs.size === 0) topicSubs.delete(topic)
+			}
+		}
+		connTopics.delete(connId)
+	}
+
+	function publish(topic: string, data: unknown): void {
+		const subs = topicSubs.get(topic)
+		if (!subs) return
+
+		for (const connId of subs) {
+			const handler = handlers.get(connId)
+			if (!handler) continue
+			try {
+				handler(data)
+			} catch {
+				/* swallow — error isolation: one broken handler must not block others */
+			}
+		}
+	}
+
+	function onMessage(connId: string, handler: (data: unknown) => void): void {
+		handlers.set(connId, handler)
+	}
+
+	function removeHandler(connId: string): void {
+		handlers.delete(connId)
+	}
+
+	function presence(topic: string): string[] {
+		const subs = topicSubs.get(topic)
+		if (!subs) return []
+		return [...subs]
+	}
+
+	return { onMessage, presence, publish, removeHandler, subscribe, unsubscribe, unsubscribeAll }
+}

package/src/realtime/longpoll.ts

@@ -0,0 +1,148 @@
+import type { ServerFrame } from "./protocol.ts"
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+interface LongPollBus {
+	subscribe(token: string, cb: (frame: ServerFrame) => void): () => void
+	deliverMessage(token: string, payload: unknown): boolean
+}
+
+interface LongPollBuffer {
+	replay(token: string, lastId: number): Array<{ id: number; data: unknown }> | null
+}
+
+export type LongPollHandlerOpts = {
+	bus: LongPollBus
+	buffer: LongPollBuffer
+	defaultWait?: number
+	maxWait?: number
+}
+
+const DEFAULT_WAIT_S = 25
+const MAX_WAIT_S = 30
+
+const JSON_HEADERS = { "Content-Type": "application/json" }
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), { headers: JSON_HEADERS, status })
+}
+
+function parseWait(raw: string | null, defaultWait: number, maxWait: number): number {
+	if (raw === null) return defaultWait
+
+	const parsed = Number(raw)
+	if (!Number.isFinite(parsed)) return defaultWait
+	if (parsed < 0) return 0
+	return Math.min(parsed, maxWait)
+}
+
+export function createLongPollHandler(opts: LongPollHandlerOpts): {
+	poll(req: Request): Promise<Response>
+	send(req: Request): Promise<Response>
+} {
+	const defaultWait = opts.defaultWait ?? DEFAULT_WAIT_S
+	const maxWait = opts.maxWait ?? MAX_WAIT_S
+
+	function poll(req: Request): Promise<Response> {
+		const url = new URL(req.url)
+		const token = url.searchParams.get("reconnectToken")
+
+		if (!token) {
+			return Promise.resolve(jsonResponse({ error: "missing reconnectToken" }, 400))
+		}
+
+		const lastId = Number(url.searchParams.get("lastId") ?? "0") || 0
+		const wait = parseWait(url.searchParams.get("wait"), defaultWait, maxWait)
+
+		const entries = opts.buffer.replay(token, lastId)
+
+		if (entries === null) {
+			return Promise.resolve(jsonResponse([{ reason: "server_restart", t: "bye" }], 404))
+		}
+
+		if (entries.length > 0) {
+			const frames: ServerFrame[] = entries.map((e) => ({
+				data: e.data,
+				id: e.id,
+				t: "msg" as const,
+			}))
+			return Promise.resolve(jsonResponse(frames))
+		}
+
+		if (wait === 0) {
+			return Promise.resolve(jsonResponse([]))
+		}
+
+		return new Promise<Response>((resolve) => {
+			let settled = false
+
+			function settle(body: ServerFrame[]): void {
+				if (settled) return
+				settled = true
+				cleanup()
+				resolve(jsonResponse(body))
+			}
+
+			const unsubscribe = opts.bus.subscribe(token, (frame) => {
+				settle([frame])
+			})
+
+			const timer = setTimeout(() => {
+				settle([])
+			}, wait * 1000)
+
+			function cleanup(): void {
+				unsubscribe()
+				clearTimeout(timer)
+				req.signal.removeEventListener("abort", onAbort)
+			}
+
+			function onAbort(): void {
+				settle([])
+			}
+
+			if (req.signal.aborted) {
+				settle([])
+				return
+			}
+			req.signal.addEventListener("abort", onAbort)
+		})
+	}
+
+	async function send(req: Request): Promise<Response> {
+		let parsed: unknown
+		try {
+			const text = await req.text()
+			if (!text) return jsonResponse({ error: "empty body" }, 400)
+			parsed = JSON.parse(text)
+		} catch {
+			return jsonResponse({ error: "invalid JSON" }, 400)
+		}
+
+		if (!isRecord(parsed)) {
+			return jsonResponse({ error: "invalid body" }, 400)
+		}
+
+		const body = parsed
+
+		const token = body.reconnectToken
+		if (typeof token !== "string") {
+			return jsonResponse({ error: "missing reconnectToken" }, 400)
+		}
+
+		if (!("data" in body)) {
+			return jsonResponse({ error: "missing data" }, 400)
+		}
+
+		const delivered = opts.bus.deliverMessage(token, body.data)
+		if (!delivered) {
+			return jsonResponse({ error: "unknown token" }, 404)
+		}
+
+		return jsonResponse({ ok: true })
+	}
+
+	return { poll, send }
+}