hono-webhooks 0.4.0 → 0.5.0

package/src/cli.ts

@@ -1,255 +1,6 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { parseArgs } from 'node:util'
-import {
-	createWebhooks,
-	describeWebhooks,
-	type Webhook,
-	type WebhooksApp
-} from './index'
-import {
-	github,
-	type SignatureScheme,
-	shopify,
-	stripe,
-	svix
-} from './signatures'
+import { cli } from './cli-commands'
 
-const schemes: Record<string, SignatureScheme<any, any>> = {
-	github,
-	shopify,
-	stripe,
-	svix
-}
-
-const HELP = `Usage: hono-webhooks <module> <command> [options]
-
-<module> exports a createWebhooks() app or an array of webhooks, as default
-or named export.
-
-Commands:
-  list                      List the webhooks
-  schema <path>             Print the JSON Schemas of the webhooks at <path>
-  test <method> <path>      Send a request through the webhooks app
-
-Options:
-  -r, --preload <module>    Import a module first (e.g. to load secrets), repeatable
-
-Options for test:
-  -b, --body <text>         Request body (JSON sets content-type: application/json)
-  -q, --query <params>      Query string, e.g. "a=1&b=2"
-  -H, --header <k: v>       Request header, repeatable
-  -s, --sign <scheme>       Sign the body: ${Object.keys(schemes).join(', ')}
-  -e, --secret-env <name>   Environment variable holding the signing secret
-
-Examples:
-  hono-webhooks ./src/webhooks.ts list
-  hono-webhooks ./src/webhooks.ts schema /orders/:id
-  hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'
-  hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
-    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET
-`
-
-const { values, positionals } = parseArgs({
-	allowPositionals: true,
-	options: {
-		help: { type: 'boolean', short: 'h' },
-		preload: { type: 'string', short: 'r', multiple: true },
-		body: { type: 'string', short: 'b' },
-		query: { type: 'string', short: 'q' },
-		header: { type: 'string', short: 'H', multiple: true },
-		sign: { type: 'string', short: 's' },
-		'secret-env': { type: 'string', short: 'e' }
-	}
-})
-
-const [modulePath, command, ...args] = positionals
-
-function fail(message: string): never {
-	console.error(message)
-	process.exit(1)
-}
-
-/** A file path relative to the cwd, or a package name. */
-const importModule = (specifier: string) =>
-	import(
-		existsSync(resolve(specifier))
-			? pathToFileURL(resolve(specifier)).href
-			: specifier
-	)
-
-function isWebhooksApp(value: unknown): value is WebhooksApp {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		Array.isArray((value as WebhooksApp).webhooks) &&
-		typeof (value as WebhooksApp).request === 'function'
-	)
-}
-
-function isWebhookArray(value: unknown): value is Webhook[] {
-	return (
-		Array.isArray(value) &&
-		value.length > 0 &&
-		value.every(
-			(item) =>
-				typeof item?.config?.path === 'string' &&
-				typeof item?.handler === 'function'
-		)
-	)
-}
-
-async function loadApp(path: string): Promise<WebhooksApp> {
-	const mod = await importModule(path)
-	const candidates = [mod.default, ...Object.values(mod)]
-	const app = candidates.find(isWebhooksApp)
-	if (app) return app
-	const webhooks = candidates.find(isWebhookArray)
-	if (webhooks) return createWebhooks(webhooks)
-	return fail(
-		`${path} exports neither a createWebhooks() app nor an array of webhooks`
-	)
-}
-
-/** Errors Node gives for TypeScript it can't load but Bun can. */
-const BUN_ONLY_ERRORS = new Set([
-	'ERR_MODULE_NOT_FOUND',
-	'ERR_UNKNOWN_FILE_EXTENSION',
-	'ERR_UNSUPPORTED_DIR_IMPORT',
-	'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX',
-	'ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING'
-])
-
-/**
- * Under Node, a Bun project's TypeScript (extensionless imports, for one)
- * fails to load. Rerun the same command under Bun when it is installed.
- */
-function rerunUnderBun(error: unknown): never {
-	const code = (error as { code?: string }).code
-	if (process.versions.bun || !code || !BUN_ONLY_ERRORS.has(code)) throw error
-	console.error(`Node can't load the module (${code}), trying Bun`)
-	const run = spawnSync('bun', process.argv.slice(1), { stdio: 'inherit' })
-	if (run.error) {
-		fail(
-			'Bun is not installed either. Run the CLI with a runtime that can load your code, e.g. bunx --bun hono-webhooks ...'
-		)
-	}
-	process.exit(run.status ?? 1)
-}
-
-async function signatureHeaders(rawBody: string) {
-	if (!values.sign) return {}
-	const scheme =
-		schemes[values.sign] ??
-		fail(
-			`Unknown scheme "${values.sign}", use one of: ${Object.keys(schemes).join(', ')}`
-		)
-	const name = values['secret-env'] ?? fail('--sign needs --secret-env <name>')
-	const secret = process.env[name] ?? fail(`${name} is not set`)
-	return scheme.sign(rawBody, secret)
-}
-
-async function main() {
-	if (values.help || !modulePath || !command) {
-		console.log(HELP)
-		return
-	}
-	let app: WebhooksApp
-	try {
-		for (const preload of values.preload ?? []) await importModule(preload)
-		app = await loadApp(modulePath)
-	} catch (error) {
-		rerunUnderBun(error)
-	}
-
-	if (command === 'list') {
-		for (const { config } of app.webhooks) {
-			const validates = [
-				...(['params', 'query', 'headers', 'body'] as const).filter(
-					(key) => config[key]
-				),
-				...(config.verify ? ['signature'] : [])
-			].join(', ')
-			console.log(
-				`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
-			)
-			if (validates) console.log(`        validates ${validates}`)
-		}
-		return
-	}
-
-	if (command === 'schema') {
-		const [path] = args
-		const descriptions = describeWebhooks(app)
-		const indexes = app.webhooks.flatMap((w, i) =>
-			w.config.path === path ? [i] : []
-		)
-		if (!indexes.length) fail(`No webhook at ${path}`)
-		for (const i of indexes) {
-			const { config } = app.webhooks[i]!
-			console.log(`${config.method} ${config.path}`)
-			for (const part of [
-				'params',
-				'query',
-				'headers',
-				'body',
-				'response'
-			] as const) {
-				if (!config[part]) continue
-				const schema = descriptions[i]!.jsonSchema[part]
-				console.log(
-					`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
-				)
-			}
-		}
-		return
-	}
-
-	if (command === 'test') {
-		const [method, path] = args
-		if (!method || !path) fail('Usage: test <method> <path>')
-		const headers = new Headers()
-		for (const header of values.header ?? []) {
-			const at = header.indexOf(':')
-			if (at < 1) fail(`Header must look like "name: value", got "${header}"`)
-			headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
-		}
-		if (values.body && !headers.has('content-type')) {
-			try {
-				JSON.parse(values.body)
-				headers.set('content-type', 'application/json')
-			} catch {
-				headers.set('content-type', 'text/plain')
-			}
-		}
-		for (const [name, value] of Object.entries(
-			await signatureHeaders(values.body ?? '')
-		)) {
-			headers.set(name, value)
-		}
-
-		const url = `${path.startsWith('/') ? path : `/${path}`}${values.query ? `?${values.query}` : ''}`
-		const start = performance.now()
-		const res = await app.request(url, {
-			method: method.toUpperCase(),
-			headers,
-			body: values.body
-		})
-		const text = await res.text()
-		let body = text
-		try {
-			body = JSON.stringify(JSON.parse(text), null, 2)
-		} catch {}
-		console.log(`${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
-		if (body) console.log(body)
-		if (!res.ok) process.exitCode = 1
-		return
-	}
-
-	fail(`Unknown command: ${command}\n\n${HELP}`)
-}
-
-await main()
+// hanzio/cli exits 2 on bad arguments; this CLI has always exited 1.
+const code = await cli.run()
+process.exitCode = code === 2 ? 1 : code

package/src/otel.ts

@@ -18,6 +18,54 @@ import {
 /** The `route` label for 404s, which match no webhook. */
 export const UNMATCHED_ROUTE = '__unmatched__'
 
+/** A metric `otelWebhooks` records, described for a metric catalog. */
+export interface WebhookMetricDefinition {
+	name: string
+	kind: 'counter' | 'histogram'
+	unit?: string
+	description: string
+	/** Attribute key to its closed set of values, or `'string'` when open. */
+	attributes: Record<string, readonly string[] | 'string'>
+}
+
+const metricAttributes = {
+	route: 'string',
+	status: ['success', 'failed']
+} as const
+
+/**
+ * The metrics `otelWebhooks` records, as data: list them in a metric
+ * catalog without creating a second recorder.
+ */
+export const webhookMetrics = [
+	{
+		name: 'webhook_request_total',
+		kind: 'counter',
+		description: 'HTTP webhook requests by route template and status',
+		attributes: metricAttributes
+	},
+	{
+		name: 'webhook_request_duration_ms',
+		kind: 'histogram',
+		unit: 'ms',
+		description: 'HTTP webhook handler duration by route template and status',
+		attributes: metricAttributes
+	}
+] as const satisfies readonly WebhookMetricDefinition[]
+
+/** `summarizeEvent(event)` plus what a completion log needs. */
+export interface WebhookCall extends WebhookEventSummary {
+	/** `error` for 5xx, `warn` for 4xx, else `info`. */
+	level: 'info' | 'warn' | 'error'
+	outcome: 'success' | 'failed' | 'validation_failed'
+}
+
+/** `console` fits, as does any logger with these three methods. */
+export type WebhookLogger = Record<
+	WebhookCall['level'],
+	(message: string, fields: Record<string, string | number>) => void
+>
+
 export interface OtelWebhooksOptions<E extends Env = any> {
 	/** @default trace.getTracer('webhooks') */
 	tracer?: Tracer
@@ -31,9 +79,19 @@ export interface OtelWebhooksOptions<E extends Env = any> {
 	 * `onEvent`'s.
 	 */
 	onWebhookCall?: (
-		call: WebhookEventSummary,
+		call: WebhookCall,
 		event: WebhookEvent<E>
 	) => void | Promise<void>
+	/**
+	 * Logs one `webhook.completed` event per request at `call.level`, with
+	 * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
+	 * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+	 * request's span, so the logger can attach to it.
+	 *
+	 * @example
+	 * logger: () => console
+	 */
+	logger?: (span: Span) => WebhookLogger
 }
 
 /**
@@ -77,8 +135,17 @@ export function otelWebhooks<E extends Env = any>(
 			)
 		},
 		onEvent: (event) => {
-			const call = summarizeEvent(event)
-			const success = call.status < 400
+			const summary = summarizeEvent(event)
+			const success = summary.status < 400
+			const call: WebhookCall = {
+				...summary,
+				level: summary.status >= 500 ? 'error' : success ? 'info' : 'warn',
+				outcome: summary.validation
+					? 'validation_failed'
+					: success
+						? 'success'
+						: 'failed'
+			}
 
 			const span = spans.get(event.c)
 			span?.setAttributes({
@@ -96,7 +163,8 @@ export function otelWebhooks<E extends Env = any>(
 				code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
 			})
 
-			if (call.route === null || !ignored.has(call.route)) {
+			const isIgnored = call.route !== null && ignored.has(call.route)
+			if (!isIgnored) {
 				// Created lazily so a meter provider registered after import still applies.
 				instruments ??= createInstruments(
 					options.meter ?? metrics.getMeter('webhooks')
@@ -109,19 +177,32 @@ export function otelWebhooks<E extends Env = any>(
 				instruments.duration.record(event.durationMs, attributes)
 			}
 
+			if (span && options.logger && call.route !== null && !isIgnored) {
+				options.logger(span)[call.level]('webhook.completed', {
+					event: 'webhook.completed',
+					route: call.route,
+					method: call.method,
+					status_code: call.status,
+					duration_ms: call.durationMs,
+					status: call.outcome,
+					...(call.error && { error_type: call.error.name })
+				})
+			}
+
 			return options.onWebhookCall?.(call, event)
 		}
 	}
 }
 
 function createInstruments(meter: Meter) {
+	const [total, duration] = webhookMetrics
 	return {
-		total: meter.createCounter('webhook_request_total', {
-			description: 'HTTP webhook requests by route template and status'
+		total: meter.createCounter(total.name, {
+			description: total.description
 		}),
-		duration: meter.createHistogram('webhook_request_duration_ms', {
-			unit: 'ms',
-			description: 'HTTP webhook handler duration by route template and status'
+		duration: meter.createHistogram(duration.name, {
+			unit: duration.unit,
+			description: duration.description
 		})
 	}
 }