@lovrozagar/honey 0.6.8 → 0.7.1

package/src/proxy.ts

@@ -1,19 +1,64 @@
+import { clientInfo, type HoneyContext } from "./context.ts"
 import { HoneyError } from "./error.ts"
+import { registerFeature } from "./feature-slots.ts"
+import { searchOfUrl } from "./request-path.ts"
 import { EK, SK } from "./types.ts"
 
-const BODY_METHODS = new Set(["POST", "PUT", "PATCH"])
-
 /* Bodies up to this size with a declared length are forwarded as bytes; larger or unsized ones
    stream (uploads). */
 const MAX_BUFFERED_BODY_BYTES = 1024 * 1024
 
+/** Default time allowed until the upstream's response headers arrive. */
+const DEFAULT_TIMEOUT_MS = 60_000
+
+/**
+ * Hop-by-hop headers (RFC 9110 §7.6.1) describe one connection and never cross a proxy, in
+ * either direction. `proxy-connection` is the pre-standard spelling clients still send.
+ * Headers a `Connection` header names are hop-by-hop too, see `stripHopByHop`.
+ */
+const HOP_BY_HOP = [
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"proxy-connection",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade",
+]
+
+/**
+ * Client-sent forwarding headers. The app's `trustProxy()` setting has already decided what is
+ * true about the client (`clientInfo`); what the client wrote is replaced, never passed on.
+ */
+const FORWARDING = ["forwarded", "x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "x-real-ip"]
+
+/** Statuses whose response can never carry a body: rebuilding one with a body throws. */
+const NULL_BODY = new Set([101, 103, 204, 205, 304])
+
+function stripHopByHop(headers: Headers, keepUpgrade: boolean): void {
+	const named = headers.get("connection")
+	if (named !== null) {
+		for (const token of named.split(",")) {
+			const name = token.trim().toLowerCase()
+			if (name === "" || (keepUpgrade && name === "upgrade")) continue
+			headers.delete(name)
+		}
+	}
+	for (const name of HOP_BY_HOP) {
+		if (keepUpgrade && name === "upgrade") continue
+		headers.delete(name)
+	}
+}
+
 /**
  * A streamed body that the destination never reads (a route without input that was sent `{}`)
  * can keep the call open until it times out: a service binding does not settle while the
  * request stream is unconsumed, and a stream teed by `request.clone()` (a body-logging
  * middleware) has no known length. Bytes have neither problem.
  */
-async function forwardBody(request: Request): Promise<BodyInit | null> {
+async function forwardBody(request: Request): Promise<ArrayBuffer | ReadableStream<Uint8Array> | null> {
 	if (request.body === null) return null
 	const declared = request.headers.get("content-length")
 	const length = declared === null ? Number.NaN : Number.parseInt(declared, 10)
@@ -21,33 +66,94 @@ async function forwardBody(request: Request): Promise<BodyInit | null> {
 	return request.body
 }
 
+/** Network-level codes runtimes put on errors when the upstream cannot be reached or drops. */
+const NETWORK_CODES = /^(?:E[A-Z0-9_]+|Connection\w*|UND_ERR\w*|UNABLE_\w+|CERT_\w+|DEPTH_ZERO\w*)$/
+
+/**
+ * Whether `error` means the upstream failed (502), as opposed to a bug in user code (500).
+ * Fetch reports network failures as a `TypeError` — so does a typo in `destination` — and the
+ * runtimes tell them apart differently: undici and Deno say "fetch failed" (with a `cause`),
+ * Bun puts a `code` on the error (`ConnectionRefused`, `ENOTFOUND`), Workers say the network
+ * connection was lost. An invalid URL is the destination's bug.
+ */
+function isUpstreamFailure(error: unknown): boolean {
+	if (!(error instanceof Error)) return false
+	const code = (error as { code?: unknown }).code
+	if (typeof code === "string") return !code.startsWith("ERR_INVALID") && NETWORK_CODES.test(code)
+	if (!(error instanceof TypeError)) return false
+	const message = error.message
+	return /^fetch failed/i.test(message) || /network connection (?:was )?lost/i.test(message)
+}
+
 /**
  * Proxy configuration — controls how requests are forwarded to downstream services.
  *
- * `destination` is the only required field. Framework builds the RequestInit
+ * `destination` is the only required field. The framework builds the RequestInit
  * (headers, body, signal, redirect) and passes it along with the resolved URL.
+ *
+ * What the framework does, both ways:
+ * - Hop-by-hop headers (`Connection`, `Keep-Alive`, `Transfer-Encoding`, `TE`, `Trailer`,
+ *   `Upgrade`, `Proxy-*`, and every header `Connection` names) are dropped. A WebSocket upgrade
+ *   keeps `Upgrade: websocket` and `Connection: upgrade`.
+ * - The client's `Host` is not sent: the upstream sees the destination's host.
+ *   `X-Forwarded-For`, `-Proto` and `-Host` describe the client as the app's `trustProxy()`
+ *   setting decided it (`clientInfo(ctx)`), with one `X-Forwarded-For` entry; whatever
+ *   forwarding headers the client sent (`Forwarded`, `X-Forwarded-*`, `X-Real-IP`) are dropped.
+ *   Configure the upstream to trust exactly one hop: this proxy.
+ * - `Expect` is dropped (the proxy reads the body itself).
+ * - Every method except GET and HEAD forwards its body (DELETE, OPTIONS, PROPFIND…).
+ * - The request follows `ctx.signal`: a client disconnect, `timeout()` or shutdown cancels the
+ *   upstream call and its body.
+ * - Redirects are returned to the client, never followed.
  */
 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.
 	 *
+	 * A network failure the runtime reports (connection refused, DNS, reset) answers 502; any
+	 * other throw — a bug in this function included — is a 500.
+	 *
 	 * @param ctx - honey context (middleware additions available)
-	 * @param url - path + query string, after rewriteUrl if provided
+	 * @param url - normalized 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>
 
+	/**
+	 * Whether the destination's Response body is already decoded, as `fetch()` always returns
+	 * it (the runtime decompresses gzip, br, zstd and keeps the `Content-Encoding` header).
+	 * When true (the default), `Content-Encoding` and `Content-Length` are dropped from encoded
+	 * responses so the headers describe the bytes the client gets. Set false when the
+	 * destination returns bytes still encoded (a store of compressed objects), so the headers
+	 * pass through.
+	 */
+	decoded?: boolean
+
+	/**
+	 * Add `X-Forwarded-For`, `-Proto` and `-Host`. Default true. Client-sent forwarding headers
+	 * are dropped either way.
+	 */
+	forwardedHeaders?: boolean
+
+	/**
+	 * Most milliseconds the upstream may stay silent while the body streams: the time between
+	 * two chunks. Omitted or non-positive: no limit (streams such as SSE may idle). A stall
+	 * aborts the upstream and errors the body. Disabled for WebSocket upgrades.
+	 */
+	idleTimeout?: number | ((ctx: TCtx) => number)
+
 	/**
 	 * 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).
+	 * The response is the proxy's own copy, so its headers can be set in place.
 	 * 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.
+	 * Set request headers before forwarding. Called after hop-by-hop and forwarding headers
+	 * are handled, so it can override any of them (including `Host` on runtimes that send it).
 	 * Static record: entries are set on the headers object.
 	 * Function: mutate headers in place.
 	 */
@@ -55,18 +161,87 @@ export type ProxyConfig<TCtx> = {
 
 	/**
 	 * Rewrite URL before passing to destination.
-	 * Receives path + query string, returns transformed URL.
+	 * Receives the normalized path + query string, returns transformed URL.
 	 */
 	rewriteUrl?: (url: string, ctx: TCtx) => string
 
 	/**
-	 * Timeout in milliseconds. Omitted: no abort. `0` or a non-positive
-	 * value: no abort. Accepts a number or a function that receives ctx
-	 * and returns a number. Disabled for WebSocket upgrades.
+	 * Most milliseconds to wait for the upstream's response headers; a later answer is a 504.
+	 * Default 60 000. `0` or a non-positive value: no limit. The body is not covered — see
+	 * `idleTimeout`. Accepts a number or a function of ctx. Disabled for WebSocket upgrades.
 	 */
 	timeout?: number | ((ctx: TCtx) => number)
 }
 
+function resolveMs<TCtx>(opt: number | ((ctx: TCtx) => number) | undefined, ctx: TCtx, fallback?: number) {
+	const ms = typeof opt === "function" ? opt(ctx) : (opt ?? fallback)
+	return ms !== undefined && ms > 0 ? ms : undefined
+}
+
+function timeoutError(): DOMException {
+	return new DOMException("upstream timed out", "TimeoutError")
+}
+
+/**
+ * The body, erroring (and aborting the upstream through `onIdle`) when the upstream sends
+ * nothing for `ms`. The clock runs only while a read is outstanding: a client that reads slowly
+ * is backpressure, not an idle upstream.
+ */
+function withIdleTimeout(body: ReadableStream<Uint8Array>, ms: number, onIdle: () => void): ReadableStream<Uint8Array> {
+	const reader = body.getReader()
+	return new ReadableStream<Uint8Array>({
+		async cancel(reason) {
+			await reader.cancel(reason)
+		},
+		async pull(controller) {
+			let timer: ReturnType<typeof setTimeout> | undefined
+			const idle = new Promise<"idle">((resolve) => {
+				timer = setTimeout(() => resolve("idle"), ms)
+			})
+			try {
+				const result = await Promise.race([reader.read(), idle])
+				if (result === "idle") {
+					onIdle()
+					const error = timeoutError()
+					/* the upstream may not react to the abort (a binding, a stub): drop it either way */
+					reader.cancel(error).catch(() => {})
+					controller.error(error)
+				} else if (result.done) {
+					controller.close()
+				} else {
+					controller.enqueue(result.value)
+				}
+			} catch (error) {
+				controller.error(error)
+			} finally {
+				clearTimeout(timer)
+			}
+		},
+	})
+}
+
+/**
+ * The response the client gets: hop-by-hop headers dropped, encoding headers made true for
+ * the bytes, in a copy whose headers are mutable (fetch() responses are immutable).
+ */
+function clientResponse(response: Response, decoded: boolean, body: ReadableStream<Uint8Array> | null): Response {
+	const headers = new Headers(response.headers)
+	stripHopByHop(headers, false)
+	if (decoded) {
+		const encoding = headers.get("content-encoding")
+		if (encoding !== null && encoding.trim().toLowerCase() !== "identity") {
+			headers.delete("content-encoding")
+			/* the length of the encoded bytes, not of the decoded body the client receives */
+			headers.delete("content-length")
+		}
+	}
+	return new Response(NULL_BODY.has(response.status) ? null : body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText,
+	})
+}
+
 /**
  * Creates a proxy handler function from config.
  * Used internally by RouteBuilder.proxy() — not meant for direct consumption.
@@ -76,39 +251,45 @@ export type ProxyConfig<TCtx> = {
  * 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
+	const decoded = config.decoded !== false
+	const forwarded = config.forwardedHeaders !== false
 
 	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"
-		const abortMs = !isWs && timeoutMs != null && timeoutMs > 0 ? timeoutMs : undefined
-
-		/* 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")
+		/* HoneyContext always has path + req + signal — safe at runtime */
+		const c = ctx as unknown as HoneyContext
+		const request = c.req
+		const method = request.method.toUpperCase()
+		const isWs = request.headers.get("upgrade")?.trim().toLowerCase() === "websocket"
+		const headerMs = isWs ? undefined : resolveMs(config.timeout, ctx, DEFAULT_TIMEOUT_MS)
+		const idleMs = isWs ? undefined : resolveMs(config.idleTimeout, ctx)
+
+		/* URL: the normalized path the router matched, plus the raw query — no new URL() */
+		const pathQuery = c.path + searchOfUrl(request.url)
+		const url = config.rewriteUrl ? config.rewriteUrl(pathQuery, ctx) : pathQuery
 
+		/* headers — one copy (the original is immutable) */
+		const headers = new Headers(request.headers)
+		stripHopByHop(headers, isWs)
 		if (isWs) {
+			headers.set("upgrade", "websocket")
 			headers.set("connection", "upgrade")
 		}
+		headers.delete("host")
+		headers.delete("expect")
+		for (const name of FORWARDING) headers.delete(name)
+		if (forwarded) {
+			const client = clientInfo(c)
+			if (client.ip !== null) headers.set("x-forwarded-for", client.ip)
+			headers.set("x-forwarded-proto", client.protocol)
+			if (client.host !== null) headers.set("x-forwarded-host", client.host)
+		}
+
+		/* body: every method that can carry one (fetch refuses a GET or HEAD body) */
+		const body = method === "GET" || method === "HEAD" ? null : await forwardBody(request)
+		if (body === null || body instanceof ArrayBuffer) {
+			/* no body, or bytes whose length fetch() computes itself */
+			headers.delete("content-length")
+		}
 
 		if (config.requestHeaders) {
 			if (typeof config.requestHeaders === "function") {
@@ -120,14 +301,17 @@ export function createProxyHandler<TCtx>(config: ProxyConfig<TCtx>): (ctx: TCtx)
 			}
 		}
 
-		/* build init — plain object, no new Request() */
-		const body = BODY_METHODS.has(method) ? await forwardBody(request) : null
+		/* one controller for the proxy's own timeouts, following the request's signal */
+		const upstream = new AbortController()
+		const clientSignal = c.signal as AbortSignal | undefined
+		const signal = clientSignal ? AbortSignal.any([clientSignal, upstream.signal]) : upstream.signal
+
 		const init: RequestInit = {
 			body: body ?? undefined,
 			headers,
 			method,
 			redirect: "manual",
-			signal: abortMs == null ? undefined : AbortSignal.timeout(abortMs),
+			signal,
 		}
 
 		/* duplex required for streaming body (Node needs it, CF handles implicitly) */
@@ -136,23 +320,29 @@ export function createProxyHandler<TCtx>(config: ProxyConfig<TCtx>): (ctx: TCtx)
 		}
 
 		/* forward */
+		let headerTimedOut = false
+		const headerTimer =
+			headerMs === undefined
+				? undefined
+				: setTimeout(() => {
+						headerTimedOut = true
+						upstream.abort(timeoutError())
+					}, headerMs)
 		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,
-				})
+			/* ours, or the destination's own AbortSignal.timeout() */
+			if (headerTimedOut || (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,
-				})
+			if (clientSignal?.aborted) throw error
+			if (isUpstreamFailure(error)) {
+				throw new HoneyError({ errorKey: EK.bad_gateway, status: SK.bad_gateway })
 			}
 			throw error
+		} finally {
+			clearTimeout(headerTimer)
 		}
 
 		/* WS 101 — return immediately, opaque */
@@ -160,13 +350,21 @@ export function createProxyHandler<TCtx>(config: ProxyConfig<TCtx>): (ctx: TCtx)
 			return response
 		}
 
+		let responseBody: ReadableStream<Uint8Array> | null = response.body
+		if (responseBody !== null && idleMs !== undefined) {
+			responseBody = withIdleTimeout(responseBody, idleMs, () => upstream.abort(timeoutError()))
+		}
+		let result = clientResponse(response, decoded, responseBody)
+
 		/* response hook */
 		if (config.onResponse) {
-			const replaced = await config.onResponse(ctx, response)
-			if (replaced) return replaced
+			const replaced = await config.onResponse(ctx, result)
+			if (replaced) result = replaced
 		}
 
-		/* stream through — zero wrapping */
-		return response
+		return result
 	}
 }
+
+/* `import "@lovrozagar/honey/proxy"` is what makes `.proxy()` available; the core never imports this module */
+registerFeature("proxy", { createProxyHandler })

package/src/python-type-emitter.ts

@@ -1,50 +1,23 @@
 import { schemaToIR } from "./codegen-ir.ts"
 import type { IRField, IRSchema } from "./codegen-ir.ts"
+import { cmpCodeUnit, pyClassName, pyString } from "./codegen-lang.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. */
+/** Attribute-safe name that keeps the original casing (`apiKeys` stays `apiKeys`).
+ * Non-identifier characters become `_`; keywords get a `_` suffix per PEP 8. */
 export function pyIdent(name: string): string {
-	if (PY_RESERVED.has(name)) return `${name}_`
-	return name.replace(/[^a-zA-Z0-9_]/g, "_")
+	let out = name.replace(/[^A-Za-z0-9_]/g, "_")
+	if (out === "") out = "value"
+	if (/^[0-9]/.test(out)) out = `_${out}`
+	if (PY_HARD_KEYWORDS.has(out) || out === "self") return `${out}_`
+	return out
 }
 
+const PY_HARD_KEYWORDS = 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".split(
+		" ",
+	),
+)
+
 function primitiveToPy(t: string): string {
 	if (t === "string") return "str"
 	if (t === "integer") return "int"
@@ -55,34 +28,52 @@ function primitiveToPy(t: string): string {
 }
 
 function formatConstPy(v: string | number | boolean): string {
-	if (typeof v === "string") return JSON.stringify(v)
+	if (typeof v === "string") return pyString(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(", ")
+		const members = ir.enum
+			.filter((v) => v !== null)
+			.map((v) => (typeof v === "string" ? pyString(v) : typeof v === "boolean" ? (v ? "True" : "False") : String(v)))
+			.join(", ")
+		if (members === "") return primitiveToPy(ir.type)
 		return `Literal[${members}]`
 	}
 	return primitiveToPy(ir.type)
 }
 
-function emitObjectPy(ir: Extract<IRSchema, { kind: "object" }>, depth: number): string {
+/** Module-level naming for generated types. Without it, nested objects render inline. */
+export type PyTypeNames = {
+	ref: (schemaName: string) => string
+	/** Hoists an object schema to a named TypedDict and returns its name. */
+	hoist: (key: string, base: string, schema: Extract<IRSchema, { kind: "object" }>) => string
+}
+
+type Ctx = { names?: PyTypeNames; parent: string; field: string }
+
+function emitObjectPy(ir: Extract<IRSchema, { kind: "object" }>, depth: number, ctx: Ctx): string {
 	const { fields, additional } = ir
 
 	if (fields.length === 0) {
 		if (additional) {
-			return `dict[str, ${irToPython(additional, depth + 1)}]`
+			return `dict[str, ${irToPythonCtx(additional, depth + 1, { ...ctx, field: `${ctx.field}Value` })}]`
 		}
 		return "dict[str, Any]"
 	}
 
-	const sortedFields = fields.slice().sort((a, b) => a.name.localeCompare(b.name))
+	if (ctx.names) {
+		const base = ctx.field === "" ? ctx.parent : `${ctx.parent}${pyClassName(ctx.field)}`
+		return ctx.names.hoist(`${ctx.parent}.${ctx.field}`, base, ir)
+	}
+
+	const sortedFields = fields.slice().sort((a, b) => cmpCodeUnit(a.name, b.name))
 	const entries = sortedFields.map((f) => {
-		const pyType = irToPython(f.schema, depth + 1)
+		const pyType = irToPythonCtx(f.schema, depth + 1, ctx)
 		const annotation = f.required ? pyType : `NotRequired[${pyType}]`
-		return `${JSON.stringify(f.name)}: ${annotation}`
+		return `${pyString(f.name)}: ${annotation}`
 	})
 
 	return `TypedDict("X", {${entries.join(", ")}})`
@@ -93,6 +84,15 @@ function emitObjectPy(ir: Extract<IRSchema, { kind: "object" }>, depth: number):
  * depth > 8 returns `Any` (mirrors TS `unknown` fallback).
  */
 export function irToPython(ir: IRSchema, depth = 0): string {
+	return irToPythonCtx(ir, depth, { field: "Value", parent: "Model" })
+}
+
+/** `irToPython` with module naming: refs map to emitted class names, nested objects are hoisted. */
+export function irToPythonNamed(ir: IRSchema, names: PyTypeNames, parent: string, field: string): string {
+	return irToPythonCtx(ir, 0, { field, names, parent })
+}
+
+function irToPythonCtx(ir: IRSchema, depth: number, ctx: Ctx): string {
 	if (depth > 8) return "Any"
 
 	switch (ir.kind) {
@@ -103,13 +103,15 @@ export function irToPython(ir: IRSchema, depth = 0): string {
 			return `Literal[${formatConstPy(ir.value)}]`
 
 		case "object":
-			return emitObjectPy(ir, depth)
+			return emitObjectPy(ir, depth, ctx)
 
 		case "array":
-			return `list[${irToPython(ir.items, depth + 1)}]`
+			return `list[${irToPythonCtx(ir.items, depth + 1, { ...ctx, field: `${ctx.field}Item` })}]`
 
 		case "tuple":
-			return `tuple[${ir.items.map((i) => irToPython(i, depth + 1)).join(", ")}]`
+			return ir.items.length === 0
+				? "tuple[()]"
+				: `tuple[${ir.items.map((i, n) => irToPythonCtx(i, depth + 1, { ...ctx, field: `${ctx.field}${n}` })).join(", ")}]`
 
 		case "union": {
 			/* union-of-const → single Literal[...] to match mixed enum behavior */
@@ -119,12 +121,17 @@ export function irToPython(ir: IRSchema, depth = 0): string {
 					.join(", ")
 				return `Literal[${members}]`
 			}
-			return ir.variants.map((v) => irToPython(v, depth + 1)).join(" | ")
+			return ir.variants
+				.map((v, n) => irToPythonCtx(v, depth + 1, { ...ctx, field: `${ctx.field}Variant${n}` }))
+				.join(" | ")
 		}
 
 		case "allOf": {
 			const allObjects = ir.parts.every((p) => p.kind === "object")
-			if (!allObjects) return "Any"
+			if (!allObjects) {
+				if (ctx.names && ir.parts.length === 1) return irToPythonCtx(ir.parts[0], depth + 1, ctx)
+				return "Any"
+			}
 			/* later parts overwrite earlier (mirrors Object.assign semantics in old jsonSchemaToPy) */
 			const mergedMap = new Map<string, IRField>()
 			const requiredSet = new Set<string>()
@@ -140,14 +147,14 @@ export function irToPython(ir: IRSchema, depth = 0): string {
 				mf.required = requiredSet.has(f.name)
 				return mf
 			})
-			return emitObjectPy({ fields: mergedFields, kind: "object" }, depth)
+			return emitObjectPy({ fields: mergedFields, kind: "object" }, depth, ctx)
 		}
 
 		case "ref":
-			return ir.name
+			return ctx.names ? ctx.names.ref(ir.name) : ir.name
 
 		case "nullable":
-			return `${irToPython(ir.inner, depth + 1)} | None`
+			return `${irToPythonCtx(ir.inner, depth + 1, ctx)} | None`
 
 		/*
 		 * binary kind arises from {type:"string", format:"binary"}.
@@ -167,3 +174,8 @@ export function jsonSchemaToPy(schema: Record<string, unknown> | undefined, dept
 	if (!schema || depth > 8) return "Any"
 	return irToPython(schemaToIR(schema), depth)
 }
+
+/** A key usable as a TypedDict class-syntax attribute (else the functional syntax is used). */
+export function isPyAttributeKey(key: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && !PY_HARD_KEYWORDS.has(key) && !key.startsWith("__")
+}