@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/cloudflare/amqp/client.ts

@@ -0,0 +1,276 @@
+const PROTOCOL_HEADER = new Uint8Array([0x41, 0x4d, 0x51, 0x50, 0, 0, 9, 1]);
+const FRAME_END = 0xce;
+const FRAME_TYPE_METHOD = 1;
+const FRAME_TYPE_HEADER = 2;
+const FRAME_TYPE_BODY = 3;
+
+const CLASS_CONNECTION = 10;
+const CLASS_CHANNEL = 20;
+const CLASS_BASIC = 60;
+
+type MethodFrame = { args: Uint8Array; channelId: number; classId: number; methodId: number };
+
+class ByteWriter {
+	private chunks: number[] = [];
+
+	build(): Uint8Array {
+		return new Uint8Array(this.chunks);
+	}
+
+	bytes(b: Uint8Array): this {
+		for (const byte of b) this.chunks.push(byte);
+		return this;
+	}
+
+	emptyTable(): this {
+		this.long(0);
+		return this;
+	}
+
+	long(v: number): this {
+		this.chunks.push((v >>> 24) & 0xff, (v >>> 16) & 0xff, (v >>> 8) & 0xff, v & 0xff);
+		return this;
+	}
+
+	longlong(v: number): this {
+		this.long(0);
+		this.long(v);
+		return this;
+	}
+
+	longstr(bytes: Uint8Array): this {
+		this.long(bytes.length);
+		this.bytes(bytes);
+		return this;
+	}
+
+	octet(v: number): this {
+		this.chunks.push(v & 0xff);
+		return this;
+	}
+
+	short(v: number): this {
+		this.chunks.push((v >>> 8) & 0xff, v & 0xff);
+		return this;
+	}
+
+	shortstr(s: string): this {
+		const bytes = new TextEncoder().encode(s);
+		this.octet(bytes.length);
+		this.bytes(bytes);
+		return this;
+	}
+}
+
+class ByteReader {
+	private buf = new Uint8Array(0);
+
+	constructor(private reader: ReadableStreamDefaultReader<Uint8Array>) {}
+
+	async readExact(n: number): Promise<Uint8Array> {
+		while (this.buf.length < n) {
+			const { done, value } = await this.reader.read();
+			if (done) throw new Error(`AMQP: connection closed while expecting ${n} bytes`);
+			const merged = new Uint8Array(this.buf.length + value.length);
+			merged.set(this.buf, 0);
+			merged.set(value, this.buf.length);
+			this.buf = merged;
+		}
+		const out = this.buf.slice(0, n);
+		this.buf = this.buf.slice(n);
+		return out;
+	}
+}
+
+function u16(b: Uint8Array, offset: number): number {
+	return (b[offset] << 8) | b[offset + 1];
+}
+
+function u32(b: Uint8Array, offset: number): number {
+	return ((b[offset] << 24) | (b[offset + 1] << 16) | (b[offset + 2] << 8) | b[offset + 3]) >>> 0;
+}
+
+async function writeFrame(
+	writer: WritableStreamDefaultWriter<Uint8Array>,
+	type: number,
+	channelId: number,
+	payload: Uint8Array
+): Promise<void> {
+	const header = new ByteWriter().octet(type).short(channelId).long(payload.length).build();
+	await writer.write(header);
+	await writer.write(payload);
+	await writer.write(new Uint8Array([FRAME_END]));
+}
+
+async function readFrame(
+	reader: ByteReader
+): Promise<{ channelId: number; payload: Uint8Array; type: number }> {
+	const header = await reader.readExact(7);
+	const type = header[0];
+	const channelId = u16(header, 1);
+	const size = u32(header, 3);
+	const payload = await reader.readExact(size);
+	const trailer = await reader.readExact(1);
+	if (trailer[0] !== FRAME_END) {
+		throw new Error(
+			`AMQP: malformed frame (expected 0xCE trailer, got 0x${trailer[0].toString(16)})`
+		);
+	}
+	return { channelId, payload, type };
+}
+
+async function readMethodFrame(reader: ByteReader): Promise<MethodFrame> {
+	const frame = await readFrame(reader);
+	if (frame.type !== FRAME_TYPE_METHOD) {
+		throw new Error(`AMQP: expected a method frame, got frame type ${frame.type}`);
+	}
+	return {
+		args: frame.payload.slice(4),
+		channelId: frame.channelId,
+		classId: u16(frame.payload, 0),
+		methodId: u16(frame.payload, 2),
+	};
+}
+
+function parseConnectionClose(args: Uint8Array): { replyCode: number; replyText: string } {
+	const replyCode = u16(args, 0);
+	const textLen = args[2];
+	const replyText = new TextDecoder().decode(args.slice(3, 3 + textLen));
+	return { replyCode, replyText };
+}
+
+export type AmqpSocket = {
+	readable: ReadableStream<Uint8Array>;
+	writable: WritableStream<Uint8Array>;
+};
+
+export type AmqpConfig = {
+	password: string;
+	username: string;
+	vpc: { connect(address: string): AmqpSocket };
+};
+
+export interface IAmqpClient {
+	publishJson(queue: string, body: unknown): Promise<void>;
+}
+
+export class AmqpClient implements IAmqpClient {
+	constructor(private readonly config: AmqpConfig) {}
+
+	async publishJson(queue: string, body: unknown): Promise<void> {
+		const { password, username, vpc } = this.config;
+		const socket = vpc.connect('127.0.0.1:5672');
+		const writer = socket.writable.getWriter();
+		const reader = new ByteReader(socket.readable.getReader());
+
+		try {
+			await writer.write(PROTOCOL_HEADER);
+
+			const start = await readMethodFrame(reader);
+			if (start.classId !== CLASS_CONNECTION || start.methodId !== 10) {
+				throw new Error(
+					`AMQP: expected Connection.Start, got class ${start.classId} method ${start.methodId}`
+				);
+			}
+
+			const saslResponse = new TextEncoder().encode(`\0${username}\0${password}`);
+			const startOk = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(11)
+				.emptyTable()
+				.shortstr('PLAIN')
+				.longstr(saslResponse)
+				.shortstr('en_US')
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, startOk);
+
+			const tune = await readMethodFrame(reader);
+			if (tune.classId !== CLASS_CONNECTION || tune.methodId !== 30) {
+				throw new Error(
+					`AMQP: expected Connection.Tune, got class ${tune.classId} method ${tune.methodId}`
+				);
+			}
+			const channelMax = u16(tune.args, 0);
+			const frameMax = u32(tune.args, 2);
+
+			const tuneOk = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(31)
+				.short(channelMax)
+				.long(frameMax)
+				.short(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, tuneOk);
+
+			const open = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(40)
+				.shortstr('/')
+				.shortstr('')
+				.octet(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, open);
+
+			const openOk = await readMethodFrame(reader);
+			if (openOk.classId !== CLASS_CONNECTION || openOk.methodId !== 41) {
+				if (openOk.classId === CLASS_CONNECTION && openOk.methodId === 50) {
+					const { replyCode, replyText } = parseConnectionClose(openOk.args);
+					throw new Error(`AMQP: connection rejected (${replyCode}): ${replyText}`);
+				}
+				throw new Error(
+					`AMQP: expected Connection.OpenOk, got class ${openOk.classId} method ${openOk.methodId}`
+				);
+			}
+
+			const channelOpen = new ByteWriter().short(CLASS_CHANNEL).short(10).shortstr('').build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 1, channelOpen);
+			const channelOpenOk = await readMethodFrame(reader);
+			if (channelOpenOk.classId !== CLASS_CHANNEL || channelOpenOk.methodId !== 11) {
+				throw new Error(
+					`AMQP: expected Channel.OpenOk, got class ${channelOpenOk.classId} method ${channelOpenOk.methodId}`
+				);
+			}
+
+			const publish = new ByteWriter()
+				.short(CLASS_BASIC)
+				.short(40)
+				.short(0)
+				.shortstr('')
+				.shortstr(queue)
+				.octet(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 1, publish);
+
+			const bodyBytes = new TextEncoder().encode(JSON.stringify(body));
+			const header = new ByteWriter()
+				.short(CLASS_BASIC)
+				.short(0)
+				.longlong(bodyBytes.length)
+				.short(0x9000)
+				.shortstr('application/json')
+				.octet(2)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_HEADER, 1, header);
+
+			await writeFrame(writer, FRAME_TYPE_BODY, 1, bodyBytes);
+
+			const close = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(50)
+				.short(200)
+				.shortstr('')
+				.short(0)
+				.short(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, close);
+			const closeOk = await readMethodFrame(reader);
+			if (closeOk.classId !== CLASS_CONNECTION || closeOk.methodId !== 51) {
+				throw new Error(
+					`AMQP: expected Connection.CloseOk, got class ${closeOk.classId} method ${closeOk.methodId}`
+				);
+			}
+		} finally {
+			await writer.close().catch(() => {});
+		}
+	}
+}

package/cloudflare/amqp/testing.ts

@@ -0,0 +1,9 @@
+import type { IAmqpClient } from './client';
+
+export class FakeAmqpClient implements IAmqpClient {
+	readonly published: { body: unknown; queue: string }[] = [];
+
+	async publishJson(queue: string, body: unknown): Promise<void> {
+		this.published.push({ body, queue });
+	}
+}

package/cloudflare/context.ts

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { EnvStore } from '../utils/env';
+
+/** Per-request/invocation cache with teardown tracking, holding the raw runtime `env`. */
+export class ContextStore {
+	private cache = new Map<string, unknown>();
+	private closers: Array<() => Promise<void>> = [];
+
+	constructor(readonly env: object) {}
+
+	async closeAll(): Promise<void> {
+		await Promise.allSettled(this.closers.map((c) => c()));
+	}
+
+	once<T>(key: string, build: () => T, close?: (v: T) => Promise<void>): T {
+		if (!this.cache.has(key)) {
+			const v = build();
+			this.cache.set(key, v);
+			if (close) this.closers.push(() => close(v));
+		}
+		return this.cache.get(key) as T;
+	}
+
+	/** For a binding whose construction is app-specific and can't be built generically here. */
+	provide<T>(key: string, value: T): void {
+		this.cache.set(key, value);
+	}
+
+	require<T>(key: string): T {
+		if (!this.cache.has(key)) {
+			throw new Error(
+				`Context key "${key}" was never provided — call store.provide("${key}", …) first`
+			);
+		}
+		return this.cache.get(key) as T;
+	}
+}
+
+const als = new AsyncLocalStorage<ContextStore>();
+
+/** Wrap one request/invocation in this — whatever gets built during the call is closed
+ *  automatically when it returns. `secretNames`: the app's list of Secrets Store binding names. */
+export async function runWithContext<T>(
+	env: object,
+	secretNames: ReadonlySet<string>,
+	fn: () => Promise<T>
+): Promise<T> {
+	await EnvStore.resolve(env, secretNames);
+	const store = new ContextStore(env);
+	try {
+		return await als.run(store, fn);
+	} finally {
+		await store.closeAll();
+	}
+}
+
+export function currentContext(): ContextStore {
+	const store = als.getStore();
+	if (!store) {
+		throw new Error(
+			'No context — call runWithContext(env, fn) at the top of the request/invocation'
+		);
+	}
+	return store;
+}

package/cloudflare/dispatch/client.ts

@@ -0,0 +1,30 @@
+/** Structural shape of the dispatch queue binding — kept minimal so kit doesn't pull in a
+ *  Cloudflare Workers type it doesn't already depend on. */
+export type DispatchQueueBinding = { send(body: unknown): Promise<void> };
+
+export interface IDispatchClient<M> {
+	send(message: M): Promise<void>;
+}
+
+/**
+ * Hands a message to the `dispatch` queue, generic over the caller's own message union `M` — kit
+ * has no notion of what a dispatch type is called. Stamps `enqueuedAt` (unix seconds) on the way
+ * out, which is the one envelope field every consumer relies on and no producer should have to
+ * remember.
+ */
+export class DispatchClient<M extends { type: string }> implements IDispatchClient<M> {
+	constructor(private readonly queue: DispatchQueueBinding) {}
+
+	async send(message: M): Promise<void> {
+		await this.queue.send({ ...message, enqueuedAt: Math.floor(Date.now() / 1000) });
+	}
+}
+
+/** Used when no `DISPATCH_QUEUE` binding exists (local dev) — logs instead of delivering, so a
+ *  missing binding degrades the same way `DevPrometheusClient` does rather than throwing. */
+export class DevDispatchClient<M extends { type: string }> implements IDispatchClient<M> {
+	async send(message: M): Promise<void> {
+		console.info('[dispatch] no DISPATCH_QUEUE binding — dropping message', { type: message.type });
+		return Promise.resolve();
+	}
+}

package/cloudflare/email/base.ts

@@ -0,0 +1,59 @@
+import { logger as defaultLogger, type LoggerClient } from '../../monitoring/logger/client';
+
+// What every email client shares: the message shape, the `IEmailClient` contract, and
+// `BaseEmailClient`, which owns the sender and the log-and-return-false `send`. A transport
+// (Workers `send_email` binding, SMTP, ...) only implements `deliver`.
+
+export type EmailAttachment = { base64Data: string; contentType: string; filename: string };
+
+export type EmailInput = {
+	attachments?: EmailAttachment[];
+	/** Display name for this message, overriding the client's `fromName`. */
+	fromName?: string;
+	html?: string;
+	replyTo?: { email: string; name?: string };
+	subject: string;
+	/** Plain-text body (or alternative to `html`). Give at least one of the two. */
+	text?: string;
+	to: string;
+};
+
+export interface IEmailClient {
+	/** Sends one message; throws on failure, for callers that retry (queue consumers). */
+	deliver(input: EmailInput): Promise<void>;
+	/** Sends one message. Logs and returns `false` on failure instead of throwing. */
+	send(input: EmailInput): Promise<boolean>;
+}
+
+export type EmailSender = {
+	/** Envelope and header sender. */
+	from: string;
+	/** Display name next to `from`. */
+	fromName?: string;
+	logger?: LoggerClient;
+};
+
+export abstract class BaseEmailClient implements IEmailClient {
+	constructor(protected readonly sender: EmailSender) {}
+
+	abstract deliver(input: EmailInput): Promise<void>;
+
+	async send(input: EmailInput): Promise<boolean> {
+		try {
+			await this.deliver(input);
+			return true;
+		} catch (err) {
+			await (this.sender.logger ?? defaultLogger).error(err, {
+				from: this.sender.from,
+				subject: input.subject,
+				to: input.to,
+			});
+			return false;
+		}
+	}
+
+	/** The display name for one message: its own, else the client's. */
+	protected nameFor(input: EmailInput): string | undefined {
+		return input.fromName ?? this.sender.fromName;
+	}
+}

package/cloudflare/email/client.ts

@@ -0,0 +1,51 @@
+import { createMimeMessage } from 'mimetext/browser';
+
+import { BaseEmailClient, type EmailInput, type EmailSender } from './base';
+
+export {
+	BaseEmailClient,
+	type EmailAttachment,
+	type EmailInput,
+	type EmailSender,
+	type IEmailClient,
+} from './base';
+
+/** The shape of a Workers `send_email` binding. */
+export type EmailBinding = { send(message: unknown): Promise<unknown> };
+
+function buildRawEmail(from: string, fromName: string | undefined, input: EmailInput): string {
+	const msg = createMimeMessage();
+	msg.setSender(fromName ? { addr: from, name: fromName } : { addr: from });
+	msg.setRecipient(input.to);
+	msg.setSubject(input.subject);
+	if (input.replyTo) msg.setHeader('Reply-To', input.replyTo.email);
+	if (input.text) msg.addMessage({ contentType: 'text/plain', data: input.text });
+	if (input.html) msg.addMessage({ contentType: 'text/html', data: input.html });
+	for (const attachment of input.attachments ?? []) {
+		msg.addAttachment({
+			contentType: attachment.contentType,
+			data: attachment.base64Data,
+			filename: attachment.filename,
+		});
+	}
+	return msg.asRaw();
+}
+
+/** Sends transactional email over a Workers `send_email` binding (Cloudflare Email Routing).
+ *  Use `DevEmailClient` where there's no binding. */
+export class EmailClient extends BaseEmailClient {
+	private readonly binding: EmailBinding;
+
+	constructor(config: EmailSender & { binding: EmailBinding }) {
+		super(config);
+		this.binding = config.binding;
+	}
+
+	async deliver(input: EmailInput): Promise<void> {
+		const { from } = this.sender;
+		// Dynamic: `cloudflare:email` only resolves inside the Workers runtime.
+		const { EmailMessage } = await import('cloudflare:email');
+		const raw = buildRawEmail(from, this.nameFor(input), input);
+		await this.binding.send(new EmailMessage(from, input.to, raw));
+	}
+}

package/cloudflare/email/dev.ts

@@ -0,0 +1,14 @@
+import type { EmailInput, IEmailClient } from './base';
+
+/** Stands in for a real client where there's no transport (local dev): logs instead of sending,
+ *  so the message is still visible. */
+export class DevEmailClient implements IEmailClient {
+	async deliver({ subject, text, to }: EmailInput): Promise<void> {
+		console.log(`[email:dev] to=${to} subject=${subject}${text ? `\n${text}` : ''}`);
+	}
+
+	async send(input: EmailInput): Promise<boolean> {
+		await this.deliver(input);
+		return true;
+	}
+}

package/cloudflare/email/smtp.ts

@@ -0,0 +1,65 @@
+import { envStore } from '../../utils/env';
+import { BaseEmailClient, type EmailInput, type EmailSender } from './base';
+
+// Email over SMTP (e.g. Amazon SES) with `worker-mailer`, which speaks SMTP over
+// `cloudflare:sockets`: for sending to any recipient, where a `send_email` binding
+// (`EmailClient`) can't. Same `IEmailClient` contract, so `DevEmailClient` and `FakeEmailClient`
+// stand in for it too.
+
+export type SmtpSettings = { host: string; password: string; port: number; username: string };
+
+/** The wrangler names of the SMTP settings: three vars and one Secrets Store secret. */
+export type SmtpKeys = { host: string; password: string; port: string; username: string };
+
+/** Connection options for worker-mailer: port 465 is implicit TLS, anything else STARTTLS. */
+export function smtpConnection({ host, password, port, username }: SmtpSettings) {
+	const implicitTls = port === 465;
+	return {
+		authType: 'plain' as const,
+		credentials: { password, username },
+		host,
+		port,
+		secure: implicitTls,
+		startTls: !implicitTls,
+	};
+}
+
+export class SmtpClient extends BaseEmailClient {
+	private readonly settings: SmtpSettings;
+
+	constructor(config: EmailSender & SmtpSettings) {
+		super(config);
+		this.settings = config;
+	}
+
+	/** A client whose settings come from `envStore()` under the names in `keys` (so the password's
+	 *  name must be among the request context's `secretNames`). */
+	static fromEnv(keys: SmtpKeys, sender: EmailSender): SmtpClient {
+		const store = envStore();
+		return new SmtpClient({
+			...sender,
+			host: store.string(keys.host),
+			password: store.secret(keys.password),
+			port: store.int(keys.port),
+			username: store.string(keys.username),
+		});
+	}
+
+	async deliver(input: EmailInput): Promise<void> {
+		// Loaded lazily: it imports cloudflare:sockets, which only exists on Workers.
+		const { WorkerMailer } = await import('worker-mailer');
+		await WorkerMailer.send(smtpConnection(this.settings), {
+			attachments: input.attachments?.map((a) => ({
+				content: a.base64Data,
+				filename: a.filename,
+				mimeType: a.contentType,
+			})),
+			from: { email: this.sender.from, name: this.nameFor(input) },
+			html: input.html,
+			reply: input.replyTo,
+			subject: input.subject,
+			text: input.text,
+			to: input.to,
+		});
+	}
+}

package/cloudflare/email/testing.ts

@@ -0,0 +1,18 @@
+import type { EmailInput, IEmailClient } from './base';
+
+/** Records every message instead of sending anything — for asserting what a service emailed,
+ *  without a mock transport. Set `succeeds = false` to simulate a delivery failure. */
+export class FakeEmailClient implements IEmailClient {
+	readonly sent: EmailInput[] = [];
+	succeeds = true;
+
+	async deliver(input: EmailInput): Promise<void> {
+		this.sent.push(input);
+		if (!this.succeeds) throw new Error('delivery failed');
+	}
+
+	async send(input: EmailInput): Promise<boolean> {
+		this.sent.push(input);
+		return this.succeeds;
+	}
+}