@lovrozagar/honey 0.1.0

package/src/realtime/protocol.ts

@@ -0,0 +1,128 @@
+export type ServerFrame =
+	| { data: unknown; id: number; t: "msg" }
+	| { t: "pong" }
+	| { reason: string; t: "bye" }
+	| { reconnectToken: string; t: "ready" }
+
+export type ClientFrame =
+	| { t: "ping" }
+	| { data: unknown; t: "msg" }
+	| { lastId: number; reconnectToken: string; t: "resume" }
+
+export type ProtocolBuffer = {
+	push(frame: { data: unknown; id: number; t: "msg" }): void
+	getAfter(lastId: number): Array<{ data: unknown; id: number; t: "msg" }>
+}
+
+export type Protocol = {
+	handleClientFrame(raw: string): ServerFrame | null
+	handleConnect(): ServerFrame
+	handleResume(lastId: number, reconnectToken: string): ServerFrame[]
+	readonly lastId: number
+	readonly reconnectToken: string
+	sendBye(reason: string): ServerFrame
+	sendMessage(data: unknown): ServerFrame
+}
+
+export function encodeServerFrame(frame: ServerFrame): string {
+	return JSON.stringify(frame)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function decodeClientFrame(raw: string): ClientFrame | null {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		return null
+	}
+
+	if (!isRecord(parsed)) {
+		return null
+	}
+
+	const obj = parsed
+
+	if (obj.t === "ping") {
+		return { t: "ping" }
+	}
+
+	if (obj.t === "msg") {
+		if (!("data" in obj)) return null
+		return { data: obj.data, t: "msg" }
+	}
+
+	if (obj.t === "resume") {
+		if (
+			typeof obj.lastId !== "number" ||
+			obj.lastId < 0 ||
+			!Number.isInteger(obj.lastId) ||
+			typeof obj.reconnectToken !== "string"
+		) {
+			return null
+		}
+		return { lastId: obj.lastId, reconnectToken: obj.reconnectToken, t: "resume" }
+	}
+
+	return null
+}
+
+export function createProtocol(opts?: { reconnectBuffer?: ProtocolBuffer }): Protocol {
+	const token = crypto.randomUUID()
+	const buffer = opts?.reconnectBuffer ?? null
+	let idCounter = 0
+
+	function handleConnect(): ServerFrame {
+		return { reconnectToken: token, t: "ready" }
+	}
+
+	function handleResume(lastId: number, reconnectToken: string): ServerFrame[] {
+		if (reconnectToken !== token || !buffer) {
+			return [{ reason: "server_restart", t: "bye" }]
+		}
+
+		const missed = buffer.getAfter(lastId)
+		return [...missed, { reconnectToken: token, t: "ready" }]
+	}
+
+	function handleClientFrame(raw: string): ServerFrame | null {
+		const frame = decodeClientFrame(raw)
+		if (!frame) return null
+
+		if (frame.t === "ping") {
+			return { t: "pong" }
+		}
+
+		return null
+	}
+
+	function sendMessage(data: unknown): ServerFrame {
+		idCounter++
+		const frame: ServerFrame = { data, id: idCounter, t: "msg" }
+		if (buffer) {
+			buffer.push({ data, id: idCounter, t: "msg" })
+		}
+		return frame
+	}
+
+	function sendBye(reason: string): ServerFrame {
+		return { reason, t: "bye" }
+	}
+
+	return {
+		handleClientFrame,
+		handleConnect,
+		handleResume,
+		get lastId() {
+			return idCounter
+		},
+		get reconnectToken() {
+			return token
+		},
+		sendBye,
+		sendMessage,
+	}
+}

package/src/realtime/route.ts

@@ -0,0 +1,104 @@
+export type ConnContext = {
+	readonly id: string
+	readonly userId: string | null
+	readonly transport: "ws" | "sse" | "longpoll"
+	readonly state: Record<string, unknown>
+	join(topic: string): void
+	leave(topic: string): void
+	send(payload: unknown): void
+	publish(topic: string, payload: unknown): void
+	close(reason?: string): void
+	on(event: "message", handler: (payload: unknown) => void): void
+	on(event: "close", handler: (reason: string) => void): void
+	readonly _handlers: { message: ((payload: unknown) => void) | null; close: ((reason: string) => void) | null }
+}
+
+export type RealtimeRouteOpts = {
+	use?: Array<(ctx: unknown, next: () => Promise<Response>) => Promise<Response>>
+	reconnectBuffer?: number
+	handler: (c: unknown, conn: ConnContext) => void | Promise<void>
+}
+
+export type RealtimeRouteHandler = {
+	handler: RealtimeRouteOpts["handler"]
+	middlewares: RealtimeRouteOpts["use"]
+	reconnectBuffer: number
+	path: string
+}
+
+export function createConnContext(opts: {
+	id: string
+	userId: string | null
+	transport: "ws" | "sse" | "longpoll"
+	bus: {
+		subscribe(connId: string, topic: string): void
+		unsubscribe(connId: string, topic: string): void
+		unsubscribeAll(connId: string): void
+		publish(topic: string, data: unknown): void
+	}
+	sendFn: (payload: unknown) => void
+	closeFn: (reason?: string) => void
+}): ConnContext {
+	const state: Record<string, unknown> = {}
+	const handlers: { message: ((payload: unknown) => void) | null; close: ((reason: string) => void) | null } = {
+		close: null,
+		message: null,
+	}
+
+	const conn: ConnContext = Object.create(null)
+
+	Object.defineProperty(conn, "id", { enumerable: true, value: opts.id, writable: false })
+	Object.defineProperty(conn, "userId", { enumerable: true, value: opts.userId, writable: false })
+	Object.defineProperty(conn, "transport", { enumerable: true, value: opts.transport, writable: false })
+	Object.defineProperty(conn, "state", { enumerable: true, get: () => state })
+	Object.defineProperty(conn, "_handlers", { enumerable: false, get: () => handlers })
+
+	Object.defineProperty(conn, "join", {
+		enumerable: true,
+		value(topic: string) {
+			opts.bus.subscribe(opts.id, topic)
+		},
+	})
+
+	Object.defineProperty(conn, "leave", {
+		enumerable: true,
+		value(topic: string) {
+			opts.bus.unsubscribe(opts.id, topic)
+		},
+	})
+
+	Object.defineProperty(conn, "send", {
+		enumerable: true,
+		value(payload: unknown) {
+			opts.sendFn(payload)
+		},
+	})
+
+	Object.defineProperty(conn, "publish", {
+		enumerable: true,
+		value(topic: string, payload: unknown) {
+			opts.bus.publish(topic, payload)
+		},
+	})
+
+	Object.defineProperty(conn, "close", {
+		enumerable: true,
+		value(reason?: string) {
+			opts.bus.unsubscribeAll(opts.id)
+			opts.closeFn(reason)
+		},
+	})
+
+	Object.defineProperty(conn, "on", {
+		enumerable: true,
+		value(event: "message" | "close", handler: ((...args: unknown[]) => void)) {
+			if (event === "message") {
+				handlers.message = handler as (payload: unknown) => void
+			} else {
+				handlers.close = handler as (reason: string) => void
+			}
+		},
+	})
+
+	return conn
+}

package/src/realtime/runtime.ts

@@ -0,0 +1,430 @@
+import type { ServerFrame } from "./protocol.ts"
+
+/* ------------------------------------------------------------------ */
+/*  Error hierarchy                                                    */
+/* ------------------------------------------------------------------ */
+
+export class RealtimeError extends Error {
+	readonly reason: string
+
+	constructor(message: string, reason: string) {
+		super(message)
+		this.reason = reason
+		this.name = "RealtimeError"
+	}
+}
+
+export class RealtimeConnectError extends RealtimeError {
+	constructor(message: string, reason: string) {
+		super(message, reason)
+		this.name = "RealtimeConnectError"
+	}
+}
+
+export class RealtimeAuthError extends RealtimeError {
+	constructor(message: string, reason: string) {
+		super(message, reason)
+		this.name = "RealtimeAuthError"
+	}
+}
+
+export class RealtimeKickedError extends RealtimeError {
+	constructor(message: string, reason: string) {
+		super(message, reason)
+		this.name = "RealtimeKickedError"
+	}
+}
+
+export class RealtimeAbortError extends RealtimeError {
+	constructor(message: string, reason: string) {
+		super(message, reason)
+		this.name = "RealtimeAbortError"
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+export type Transport = "ws" | "sse" | "longpoll"
+export type ConnectionState = "idle" | "connecting" | "connected" | "draining" | "reconnecting" | "closed"
+
+export type TransportAdapter = {
+	connect(url: string, opts: TransportOpts): TransportConnection
+}
+
+export type TransportConnection = {
+	send(data: string): void
+	close(): void
+	onFrame: (frame: ServerFrame) => void
+	onClose: (reason: string) => void
+	onError: (err: unknown) => void
+}
+
+export type TransportOpts = {
+	signal?: AbortSignal
+	headers?: Record<string, string>
+	lastId?: number
+	reconnectToken?: string
+}
+
+/* ------------------------------------------------------------------ */
+/*  KeepaliveLoop                                                      */
+/* ------------------------------------------------------------------ */
+
+export function createKeepaliveLoop(opts: {
+	transport: Transport
+	sendPing: () => void
+	onDead: () => void
+	interval?: number
+	timeout?: number
+}): { start(): void; stop(): void; onPong(): void; onFrame(): void } {
+	const interval = opts.interval ?? 25_000
+	const timeout = opts.timeout ?? 60_000
+	const transport = opts.transport
+
+	let pingTimer: ReturnType<typeof setInterval> | null = null
+	let deadTimer: ReturnType<typeof setTimeout> | null = null
+
+	function clearAll(): void {
+		if (pingTimer !== null) {
+			clearInterval(pingTimer)
+			pingTimer = null
+		}
+		if (deadTimer !== null) {
+			clearTimeout(deadTimer)
+			deadTimer = null
+		}
+	}
+
+	function resetDeadTimer(): void {
+		if (deadTimer !== null) {
+			clearTimeout(deadTimer)
+		}
+		deadTimer = setTimeout(() => {
+			opts.onDead()
+		}, timeout)
+	}
+
+	function start(): void {
+		/* Idempotent — stop first to avoid stacking timers */
+		clearAll()
+
+		if (transport === "longpoll") return
+
+		if (transport === "ws") {
+			pingTimer = setInterval(() => {
+				opts.sendPing()
+			}, interval)
+			resetDeadTimer()
+			return
+		}
+
+		if (transport === "sse") {
+			/* SSE: no pings, just idle timer based on frames from server */
+			resetDeadTimer()
+		}
+	}
+
+	function stop(): void {
+		clearAll()
+	}
+
+	function onPong(): void {
+		/* Only meaningful for WS — reset the dead timer */
+		if (deadTimer !== null) {
+			resetDeadTimer()
+		}
+	}
+
+	function onFrame(): void {
+		/* Meaningful for SSE — reset idle timer on any frame */
+		if (transport === "sse" && deadTimer !== null) {
+			resetDeadTimer()
+		}
+	}
+
+	return { onFrame, onPong, start, stop }
+}
+
+/* ------------------------------------------------------------------ */
+/*  FallbackChain                                                      */
+/* ------------------------------------------------------------------ */
+
+const DEFAULT_FALLBACK_TIMEOUT = 3000
+
+export function createFallbackChain(opts: {
+	transports: TransportAdapter[]
+	timeout?: number
+}): {
+	connect(url: string, transportOpts: TransportOpts): Promise<{ conn: TransportConnection; transport: Transport }>
+	readonly provenTransport: Transport | null
+} {
+	const timeout = opts.timeout ?? DEFAULT_FALLBACK_TIMEOUT
+	let proven: Transport | null = null
+
+	function tryTransport(
+		adapter: TransportAdapter,
+		url: string,
+		transportOpts: TransportOpts,
+	): Promise<TransportConnection> {
+		return new Promise((resolve, reject) => {
+			const conn = adapter.connect(url, transportOpts)
+
+			const timer = setTimeout(() => {
+				conn.close()
+				reject(new Error("timeout"))
+			}, timeout)
+
+			const originalOnFrame = conn.onFrame
+			conn.onFrame = (frame: ServerFrame) => {
+				if (frame.t === "ready") {
+					clearTimeout(timer)
+					conn.onFrame = originalOnFrame
+					resolve(conn)
+				} else {
+					originalOnFrame(frame)
+				}
+			}
+
+			conn.onError = (err: unknown) => {
+				clearTimeout(timer)
+				conn.close()
+				reject(err)
+			}
+
+			conn.onClose = (reason: string) => {
+				clearTimeout(timer)
+				reject(new Error(reason))
+			}
+		})
+	}
+
+	function connect(
+		url: string,
+		transportOpts: TransportOpts,
+	): Promise<{ conn: TransportConnection; transport: Transport }> {
+		const transports = opts.transports
+
+		if (transports.length === 0) {
+			const p = Promise.reject(new RealtimeConnectError("No transports configured", "no_transports"))
+			p.catch(() => {})
+			return p
+		}
+
+		const p = connectInternal(url, transportOpts, transports)
+		p.catch(() => {})
+		return p
+	}
+
+	async function connectInternal(
+		url: string,
+		transportOpts: TransportOpts,
+		transports: TransportAdapter[],
+	): Promise<{ conn: TransportConnection; transport: Transport }> {
+
+		/* If we have a proven transport, try it first (it's at a specific index) */
+		if (proven !== null) {
+			/* proven refers to index position — try that adapter directly */
+			const provenIndex = provenIndexStore
+			if (provenIndex !== null && provenIndex < transports.length) {
+				try {
+					const conn = await tryTransport(transports[provenIndex], url, transportOpts)
+					return { conn, transport: proven }
+				} catch {
+					/* Proven transport failed — fall through to full chain */
+				}
+			}
+		}
+
+		for (let i = 0; i < transports.length; i++) {
+			try {
+				const conn = await tryTransport(transports[i], url, transportOpts)
+				/* Record proven transport — we use the index to map to a transport name */
+				let transportName: Transport = "longpoll"
+				if (i === 0) transportName = "ws"
+				else if (i === 1) transportName = "sse"
+				proven = transportName
+				provenIndexStore = i
+				return { conn, transport: transportName }
+			} catch {
+				/* Try next */
+			}
+		}
+
+		throw new RealtimeConnectError("All transports failed", "all_failed")
+	}
+
+	let provenIndexStore: number | null = null
+
+	return {
+		connect,
+		get provenTransport() {
+			return proven
+		},
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/*  ResumableConnection                                                 */
+/* ------------------------------------------------------------------ */
+
+export type ResumableConnectionOpts = {
+	url: string
+	token?: () => string | Promise<string>
+	onAuthExpired?: () => Promise<string | null>
+	onReconnecting?: (attempt: number, transport: Transport) => void
+	onReconnected?: () => void
+	signal?: AbortSignal
+	transports?: Transport[]
+	keepaliveInterval?: number
+}
+
+type QueueEntry =
+	| { type: "value"; value: unknown }
+	| { type: "done" }
+	| { type: "error"; error: unknown }
+
+export function createResumableConnection(opts: ResumableConnectionOpts): {
+	readonly state: ConnectionState
+	send(data: unknown): void
+	close(reason?: string): void
+	[Symbol.asyncIterator](): AsyncIterableIterator<unknown>
+} {
+	let state: ConnectionState = "idle"
+	let currentConn: TransportConnection | null = null
+	let started = false
+
+	/* Check if already aborted */
+	if (opts.signal?.aborted) {
+		state = "closed"
+	}
+
+	/* Queue-based async iterator infrastructure */
+	const queue: QueueEntry[] = []
+	let pending: {
+		resolve: (result: IteratorResult<unknown>) => void
+		reject: (err: unknown) => void
+	} | null = null
+
+	function enqueue(entry: QueueEntry): void {
+		if (pending) {
+			const { resolve, reject } = pending
+			pending = null
+
+			if (entry.type === "value") {
+				resolve({ done: false, value: entry.value })
+			} else if (entry.type === "done") {
+				resolve({ done: true, value: undefined })
+			} else {
+				reject(entry.error)
+			}
+		} else {
+			queue.push(entry)
+		}
+	}
+
+	function terminate(entry: QueueEntry): void {
+		enqueue(entry)
+	}
+
+	function handleClose(): void {
+		if (state === "closed") return
+		state = "closed"
+		if (currentConn) {
+			currentConn.close()
+			currentConn = null
+		}
+		terminate({ type: "done" })
+	}
+
+	function handleAbort(): void {
+		if (state === "closed") return
+		state = "closed"
+		if (currentConn) {
+			currentConn.close()
+			currentConn = null
+		}
+		terminate({ error: new RealtimeAbortError("Connection aborted", "aborted"), type: "error" })
+	}
+
+	/* Listen for abort signal */
+	if (opts.signal && !opts.signal.aborted) {
+		opts.signal.addEventListener("abort", () => {
+			handleAbort()
+		}, { once: true })
+	}
+
+	function startConnection(): void {
+		if (started || state === "closed") return
+		started = true
+		state = "connecting"
+
+		/* Kick off connection in a microtask */
+		queueMicrotask(() => {
+			if (state === "closed") return
+
+			/* In a real implementation, this would use createFallbackChain.
+			   For now, state transitions are driven by external transport frames. */
+		})
+	}
+
+	function send(data: unknown): void {
+		if (state === "closed" || !currentConn) return
+		currentConn.send(JSON.stringify(data))
+	}
+
+	function close(_reason?: string): void {
+		handleClose()
+	}
+
+	function next(): Promise<IteratorResult<unknown>> {
+		/* First next() call triggers connection */
+		if (!started && state !== "closed") {
+			startConnection()
+		}
+
+		/* Check queue first */
+		if (queue.length > 0) {
+			const entry = queue.shift()
+			if (!entry || entry.type === "done") {
+				return Promise.resolve({ done: true, value: undefined })
+			}
+			if (entry.type === "value") {
+				return Promise.resolve({ done: false, value: entry.value })
+			}
+			return Promise.reject(entry.error)
+		}
+
+		/* If already closed, return done */
+		if (state === "closed") {
+			return Promise.resolve({ done: true, value: undefined })
+		}
+
+		/* Wait for next entry — attach a no-op catch to suppress Node's
+		   unhandled-rejection warning while the caller awaits the promise */
+		const promise = new Promise<IteratorResult<unknown>>((resolve, reject) => {
+			pending = { reject, resolve }
+		})
+		promise.catch(() => {})
+		return promise
+	}
+
+	function asyncIterator(): AsyncIterableIterator<unknown> {
+		return {
+			next,
+			[Symbol.asyncIterator]() {
+				return this
+			},
+		}
+	}
+
+	return {
+		[Symbol.asyncIterator]: asyncIterator,
+		close,
+		send,
+		get state() {
+			return state
+		},
+	}
+}

package/src/request-id.ts

@@ -0,0 +1,23 @@
+import type { MiddlewareFn } from "./middleware.ts"
+
+type RequestIdOptions = {
+	generator?: () => string
+	header?: string
+}
+
+export function requestId(
+	options?: RequestIdOptions,
+): MiddlewareFn<{ req: Request }, { requestId: string }> {
+	const headerName = options?.header ?? "x-request-id"
+	const generate = options?.generator ?? (() => crypto.randomUUID())
+
+	const mw: MiddlewareFn<{ req: Request }, { requestId: string }> = async (ctx, next) => {
+		const existing = ctx.req.headers.get(headerName)
+		const id = existing ?? generate()
+		const response = await next({ requestId: id })
+		response.headers.set(headerName, id)
+		return response
+	}
+
+	return mw
+}

package/src/request-to-curl.ts

@@ -0,0 +1,34 @@
+export type RequestToCurlOptions = {
+	excludeHeader?: (name: string, value: string) => boolean
+}
+
+function shellEscape(value: string): string {
+	return value.replace(/'/g, "'\\''")
+}
+
+/**
+ * Convert a native Request into a curl command string.
+ * The request is cloned so reading the body does not consume the original stream.
+ */
+export async function requestToCurl(
+	request: Request,
+	options?: RequestToCurlOptions,
+): Promise<string> {
+	const clonedRequest = request.clone()
+	const parts: string[] = [`curl -X ${clonedRequest.method}`]
+
+	for (const [name, value] of clonedRequest.headers.entries()) {
+		if (options?.excludeHeader?.(name, value) === true) continue
+		parts.push(`-H '${shellEscape(name)}: ${shellEscape(value)}'`)
+	}
+
+	const body = await clonedRequest.text()
+
+	if (body.length > 0) {
+		parts.push(`--data-raw '${shellEscape(body)}'`)
+	}
+
+	parts.push(`'${shellEscape(clonedRequest.url)}'`)
+
+	return parts.join(" ")
+}