@fabrika/app 0.4.8 → 0.5.0

package/src/implement/index.ts

@@ -1,6 +1,15 @@
 // @fabrika/app/implement — serving a contract: `serve` binds the handlers its endpoints carry, `boot` (called only by
 // the generated entrypoint, through a runtime adapter) serves it. Imports `node:async_hooks`, so it is not browser-safe.
 // `implement` (a mirrored handler tree) is the framework's own test entry, `./implement`, and no application's.
+export {
+	EmailDeliveryError,
+	type EmailDeliveryErrorCode,
+	type EmailDeliveryOutcome,
+	type EmailDeliveryResult,
+	type EmailSender,
+	type EmailSenderCapabilities,
+	mayRetryDelivery,
+} from '@fabrika/email'
 export { FILE_SWEEP_JOB } from '../files/collections'
 export type { FileCollectionHandle, FileCollectionReader, FileListing, ListedFile, OpenedFile } from '../files/handle'
 export {
@@ -15,7 +24,7 @@ export {
 export { crashEnvelope, type OperationsReport, type OperationsReporter, reportEnvelope } from '../jobs/report'
 export { type ContractJobs, type JobClock, JobError, type JobFailureCode, type JobRunOptions, type JobRunResult } from '../jobs/runner'
 export { secretScrubber } from '../jobs/scrub'
-export type { JobContext, JobHandler, JobHandlersOf, JobPrincipal } from '../jobs/types'
+export type { AppMail, AppMailMessage, JobContext, JobHandler, JobHandlersOf, JobPrincipal } from '../jobs/types'
 export { LINK_BOOTSTRAP_SCRIPT } from './anonymous'
 export { boot, BootError, type BootOptions, type ContractApp, type IamKeySource } from './boot'
 export { readBoundedBytes, REQUEST_BUDGET_MS } from './bounded'

package/src/implement/invocation.ts

@@ -3,7 +3,7 @@
 // commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
 // is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
 
-import type { ContractArtifact } from '@fabrika/auth-core'
+import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
 import {
 	type DataAccess,
 	type DataHandles,
@@ -16,6 +16,7 @@ import {
 } from '@fabrika/db/framework'
 import type { DataKind, UnscopedMode } from '@fabrika/db/tables'
 import type { SqlMode } from '../contract/context'
+import { DECLARED_FIELDS } from '../contract/declaration'
 import type { FileSite } from '../files/collections'
 import { CapabilityRefusedError, isActiveRequest, type RequestFrame } from './capability'
 import { ServerFault } from './faults'
@@ -26,6 +27,8 @@ export interface SiteDeclaration {
 	readonly unscoped: Readonly<Record<string, UnscopedMode>>
 	readonly connect: readonly string[]
 	readonly issues: string | null
+	readonly then: string | null
+	readonly mailer: JobMailer | null
 }
 
 export type SiteFunction = (args: { readonly input?: unknown; readonly ctx: object }) => unknown
@@ -53,8 +56,14 @@ export function isSiteHandler(node: unknown): node is SiteHandler {
 	return typeof node === 'object' && node !== null && sites.has(node)
 }
 
-const DECLARED_FIELDS: readonly string[] = ['sql', 'unscoped', 'connect', 'issues']
-const NO_DECLARATION: SiteDeclaration = Object.freeze({ sql: null, unscoped: Object.freeze({}), connect: Object.freeze([]), issues: null })
+const NO_DECLARATION: SiteDeclaration = Object.freeze({
+	sql: null,
+	unscoped: Object.freeze({}),
+	connect: Object.freeze([]),
+	issues: null,
+	then: null,
+	mailer: null,
+})
 
 function isPlainObject(value: unknown): value is Readonly<Record<string, unknown>> {
 	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -81,7 +90,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
 		return NO_DECLARATION
 	}
 	for (const key of Object.keys(declared)) {
-		if (!DECLARED_FIELDS.includes(key)) {
+		if (!DECLARED_FIELDS.some((field) => field === key)) {
 			problems.push(`${where}: '${key}' is no declaration (declarations: ${DECLARED_FIELDS.join(', ')})`)
 		}
 	}
@@ -122,11 +131,22 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
 	if (issues !== undefined && typeof issues !== 'string') {
 		problems.push(`${where}: issues is not the name of a link mount`)
 	}
+	const then = ownField(declared, 'then')
+	if (then !== undefined && typeof then !== 'string') {
+		problems.push(`${where}: then is not the name of a job`)
+	}
+	const mailerField = ownField(declared, 'mailer')
+	const mailer = JOB_MAILERS.find((transport) => transport === mailerField) ?? null
+	if (mailerField !== undefined && mailer === null) {
+		problems.push(`${where}: mailer is not 'installation' or 'own'`)
+	}
 	return Object.freeze({
 		sql: sql === 'read' || sql === 'write' ? sql : null,
 		unscoped: Object.freeze(unscoped),
 		connect: Object.freeze(connectors),
 		issues: typeof issues === 'string' ? issues : null,
+		then: typeof then === 'string' ? then : null,
+		mailer,
 	})
 }
 
@@ -167,13 +187,25 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
 			unscoped: Object.freeze({ ...reach.unscoped }),
 			connect: Object.freeze([...reach.connect]),
 			issues: reach.issues,
+			then: reach.then ?? null,
+			mailer: reach.mailer ?? null,
 		})
 }
 
-/** A declaration as one comparable line: its fields in a fixed order, its tables and connectors sorted. */
+/**
+ * A declaration as one comparable line: its fields in a fixed order, its tables and connectors sorted; `then` and
+ * `mailer` only when declared.
+ */
 function describeDeclaration(declaration: SiteDeclaration): string {
 	const unscoped = Object.entries(declaration.unscoped).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-	return JSON.stringify({ sql: declaration.sql, unscoped, connect: [...declaration.connect].sort(), issues: declaration.issues })
+	return JSON.stringify({
+		sql: declaration.sql,
+		unscoped,
+		connect: [...declaration.connect].sort(),
+		issues: declaration.issues,
+		...(declaration.then === null ? {} : { then: declaration.then }),
+		...(declaration.mailer === null ? {} : { mailer: declaration.mailer }),
+	})
 }
 
 /**

package/src/implement/serve.ts

@@ -1,6 +1,7 @@
 // `serve(contract, { database, deps })`: how `src/app.ts` serves a contract of the staged kit. Its handlers sit
 // beside their endpoints, so there is no handler tree to pass: `serve` collects the one `boot` binds by endpoint id.
 
+import type { EmailSender } from '@fabrika/email'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { isProcedure, type ProcedureTreeDeclaration, SURFACE_SECTIONS } from '../contract/declaration'
 import type { AnyContract, Schema } from '../contract/define'
@@ -61,6 +62,8 @@ export interface ServeOptions {
 	/** `scoped(tables)` of `@fabrika/db`, which `boot` binds, or `null` for a kit without tables (`defineApp(vocabulary)`). */
 	readonly database: ImplementationDatabase | null
 	readonly deps?: AppDeps<unknown>
+	/** The transport of the jobs that declare `mailer: 'own'`, built once at boot from the application's own variables. */
+	readonly mail?: (env: ApplicationEnvironment) => EmailSender | null
 }
 
 /**
@@ -86,6 +89,7 @@ export function serve<const C extends AnyContract>(contract: C, options: ServeOp
 		database: options.database,
 		connect: snapshotsOf(contract),
 		handlers: (env, runtime) => handlerTree(contract, build?.(env, runtime) ?? ((work) => work())),
+		...(options.mail === undefined ? {} : { mail: options.mail }),
 	})
 }
 

package/src/jobs/mail.ts

@@ -0,0 +1,261 @@
+// `ctx.mail` of a job that declares `mailer`, over the transport `boot` resolved: the installation's (`FABRIKA_EMAIL_*`),
+// the application's own (`serve(contract, { mail })`) or the test kit's stand-in. An installation without a transport
+// says so (`FABRIKA_EMAIL_PROVIDER=none`): its jobs get `ctx.mail` that is not available, and each send waits for one.
+// Each key carries the prefix of the installation and the application environment, so senders on one provider account
+// never share a key. Nothing here logs a message or a key.
+
+import { type ContractArtifact, JOB_SITE_PREFIX, type JobMailer, sha256Hex } from '@fabrika/auth-core'
+import {
+	EMAIL_PROVIDER_VARIABLE,
+	EmailDeliveryError,
+	type EmailDeliveryResult,
+	type EmailMessage,
+	type EmailProviderRegistry,
+	type EmailSender,
+	emailSenderFromEnv,
+	mayRetryDelivery,
+	NO_EMAIL_PROVIDER,
+	pickEmailEnvironment,
+} from '@fabrika/email'
+import { z } from 'zod/v4'
+import type { ApplicationEnvironment } from '../implement/implement'
+import type { AppMail, AppMailMessage } from './types'
+
+export const MAX_APP_MAIL_KEY_LENGTH = 200
+const PREFIX_DIGEST_LENGTH = 32
+const APP_MAIL_KEY = new RegExp(`^[\\x21-\\x7E]{1,${MAX_APP_MAIL_KEY_LENGTH}}$`)
+
+/** Whose keys a prefix separates: the installation, by IAM's public origin, and the application environment in it. */
+export interface MailKeyScope {
+	/** `FABRIKA_IAM_ISSUER` as an origin: it tells installations, and the local stack, apart. */
+	readonly issuer: string
+	/** `FABRIKA_IAM_APP_ID`, `<app>@<env>`. */
+	readonly appId: string
+}
+
+/**
+ * `fabrika:<the first 32 hex of sha256('<issuer>\n<app>@<env>')>:` — 41 characters, whatever the names hold. Renaming
+ * IAM's domain changes every key once, so a message in flight across the rename may be sent again.
+ */
+export function mailKeyPrefix(scope: MailKeyScope): string {
+	return `fabrika:${sha256Hex(`${scope.issuer}\n${scope.appId}`).slice(0, PREFIX_DIGEST_LENGTH)}:`
+}
+
+/** The key the transport receives for the application's `key`. */
+export function transportMailKey(scope: MailKeyScope, key: string): string {
+	return `${mailKeyPrefix(scope)}${key}`
+}
+
+/** A mailer job's transport: one that sends, or the stated absence of one, whose every send fails `mail_not_configured`. */
+export interface JobMailTransport {
+	readonly sender: EmailSender
+	readonly available: boolean
+}
+
+/** The transports of a contract's mailer jobs, resolved once by `boot`; `null` where no job declares that mailer. */
+export interface MailTransports {
+	readonly installation: JobMailTransport | null
+	readonly own: JobMailTransport | null
+	readonly keyPrefix: string
+}
+
+/** The test kit's transport for every mailer job: a stand-in sender, or `'none'` for an installation without mail. */
+export type MailStandIn = EmailSender | 'none'
+
+/** The application's own transport, built once at boot from its own variables; `null` when they configure none. */
+export type OwnMailTransport = (env: ApplicationEnvironment) => EmailSender | null
+
+export interface JobMailInput {
+	readonly transport: JobMailTransport
+	readonly keyPrefix: string
+	/** The attempt's `ctx.signal`: it aborts every send of the attempt. */
+	readonly signal: AbortSignal
+	/** Throws once the attempt has ended. */
+	readonly assertLive: () => void
+}
+
+export function jobMail(input: JobMailInput): AppMail {
+	const { transport: { sender, available }, keyPrefix, signal: attempt, assertLive } = input
+	return Object.freeze({
+		available,
+		capabilities: sender.capabilities,
+		async send(message: AppMailMessage, signal?: AbortSignal): Promise<EmailDeliveryResult> {
+			assertLive()
+			const key: unknown = message.idempotencyKey
+			if (typeof key !== 'string' || !APP_MAIL_KEY.test(key)) {
+				throw new EmailDeliveryError(`Email idempotency key is not 1..${MAX_APP_MAIL_KEY_LENGTH} visible ASCII characters`, { code: 'invalid_message' })
+			}
+			const transported: EmailMessage = {
+				to: message.to,
+				subject: message.subject,
+				text: message.text,
+				...(message.html === undefined ? {} : { html: message.html }),
+				idempotencyKey: `${keyPrefix}${key}`,
+				...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
+				...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+			}
+			try {
+				return await sender.send(transported, signal === undefined ? attempt : AbortSignal.any([attempt, signal]))
+			} catch (error) {
+				if (error instanceof EmailDeliveryError) {
+					throw error
+				}
+				// An application's own transport may throw anything, and its message may quote a credential: it is dropped unread.
+				throw new EmailDeliveryError('The transport failed', { code: 'provider_unavailable' })
+			}
+		},
+		mayRetry: (error: unknown): boolean => error instanceof EmailDeliveryError && mayRetryDelivery(error, sender.capabilities),
+	})
+}
+
+export interface MailTransportInput {
+	readonly artifact: ContractArtifact
+	/** The framework's variables, whose `FABRIKA_EMAIL_*` configure the installation's transport. */
+	readonly framework: Readonly<Record<string, string>>
+	readonly application: ApplicationEnvironment
+	/** `serve(contract, { mail })`. */
+	readonly own: OwnMailTransport | undefined
+	/** The test kit's transport for every mailer job; the variables and `own` are then not read. */
+	readonly standIn: MailStandIn | undefined
+	readonly registry: EmailProviderRegistry
+	/** Whose keys the prefix separates. */
+	readonly keyScope: MailKeyScope
+	/** A local composition: a missing transport is no mail, as `FABRIKA_EMAIL_PROVIDER=none` is, instead of a refused boot. */
+	readonly local: boolean
+}
+
+/** The transports of the contract's mailer jobs, or why one of them cannot send, added to `problems`. */
+export function resolveMailTransports(input: MailTransportInput, problems: string[]): MailTransports {
+	const keyPrefix = mailKeyPrefix(input.keyScope)
+	const jobs = mailerJobs(input.artifact)
+	if (input.own === undefined) {
+		for (const name of jobs.own) {
+			problems.push(`job '${name}' declares mailer: 'own', and serve(contract, { … }) has no mail: pass mail: (env) => EmailSender`)
+		}
+	} else if (jobs.own.length === 0) {
+		problems.push(`serve(contract, { mail }) builds a transport no job uses: declare mailer: 'own' on the job that sends, or remove mail`)
+	}
+	if (input.standIn !== undefined) {
+		const standIn = input.standIn === 'none' ? NO_MAIL : { sender: input.standIn, available: true }
+		return {
+			installation: jobs.installation.length === 0 ? null : standIn,
+			own: jobs.own.length === 0 ? null : standIn,
+			keyPrefix,
+		}
+	}
+	return {
+		installation: jobs.installation.length === 0 ? null : installationTransport(jobs.installation, input, problems),
+		own: jobs.own.length === 0 ? null : ownTransport(jobs.own, input, problems),
+		keyPrefix,
+	}
+}
+
+/** The names of the jobs that declare each mailer, by the approved artifact. */
+function mailerJobs(artifact: ContractArtifact): Readonly<Record<JobMailer, readonly string[]>> {
+	const jobs: Record<JobMailer, string[]> = { installation: [], own: [] }
+	for (const name of Object.keys(artifact.jobs)) {
+		const mailer = artifact.declared?.[`${JOB_SITE_PREFIX}${name}`]?.mailer
+		if (mailer !== undefined) {
+			jobs[mailer].push(name)
+		}
+	}
+	return jobs
+}
+
+function installationTransport(names: readonly string[], input: MailTransportInput, problems: string[]): JobMailTransport | null {
+	const env = pickEmailEnvironment(input.framework)
+	let sender: EmailSender | null
+	try {
+		sender = emailSenderFromEnv(env, input.registry)
+	} catch (error) {
+		if (!(error instanceof EmailDeliveryError)) {
+			throw error
+		}
+		// Its message names variables, never their values; a local installation is refused too, as it is misconfigured.
+		problems.push(`the installation's mail transport: ${error.message}`)
+		return null
+	}
+	if (sender !== null) {
+		return { sender, available: true }
+	}
+	if (env[EMAIL_PROVIDER_VARIABLE] === NO_EMAIL_PROVIDER || input.local) {
+		return noMail(names, 'installation')
+	}
+	// Control writes the variable on every deploy that needs it, `none` included: its absence means no deploy wrote it.
+	for (const name of names) {
+		problems.push(
+			`job '${name}' declares mailer: 'installation', and FABRIKA_EMAIL_PROVIDER is not set: Control writes it when it deploys the application (none for an installation without a transport)`,
+		)
+	}
+	return null
+}
+
+function ownTransport(names: readonly string[], input: MailTransportInput, problems: string[]): JobMailTransport | null {
+	if (input.own === undefined) {
+		return null
+	}
+	let built: unknown
+	try {
+		built = input.own(input.application)
+	} catch (error) {
+		if (!(error instanceof EmailDeliveryError)) {
+			throw error
+		}
+		problems.push(`serve's mail: ${error.message}`)
+		return null
+	}
+	const sender = parseSender(built)
+	if (sender === undefined) {
+		problems.push("serve's mail returned no EmailSender (capabilities and send(message, signal))")
+		return null
+	}
+	if (sender !== null) {
+		return { sender, available: true }
+	}
+	if (input.local) {
+		return noMail(names, 'own')
+	}
+	for (const name of names) {
+		problems.push(`job '${name}' declares mailer: 'own', and serve's mail built no transport from the application's variables`)
+	}
+	return null
+}
+
+const SenderCapabilities = z.object({ idempotent: z.boolean(), confirmation: z.enum(['sync', 'queued']), maxBatch: z.int().positive() })
+
+/** What `serve`'s `mail` returned: a sender, `null` for none, `undefined` for anything else. */
+function parseSender(value: unknown): EmailSender | null | undefined {
+	if (value === null) {
+		return null
+	}
+	if (typeof value !== 'object') {
+		return undefined
+	}
+	const send: unknown = Reflect.get(value, 'send')
+	const capabilities = SenderCapabilities.safeParse(Reflect.get(value, 'capabilities'))
+	if (typeof send !== 'function' || !capabilities.success) {
+		return undefined
+	}
+	return Object.freeze({
+		capabilities: Object.freeze(capabilities.data),
+		send: (message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> => Reflect.apply(send, value, [message, signal]),
+	})
+}
+
+/** Where the installation has no transport: every send fails `not_sent`, and the boot does not. */
+export const NO_MAIL: JobMailTransport = Object.freeze({
+	sender: Object.freeze({
+		capabilities: Object.freeze({ idempotent: true, confirmation: 'sync', maxBatch: 1 }),
+		send: () => Promise.reject(new EmailDeliveryError('This installation has no mail transport', { code: 'mail_not_configured' })),
+	}),
+	available: false,
+})
+
+function noMail(names: readonly string[], kind: JobMailer): JobMailTransport {
+	for (const name of names) {
+		console.warn(
+			`fabrika: job '${name}' sends mail, and this installation has no ${kind} mail transport: ctx.mail.available is false, and every send fails with mail_not_configured`,
+		)
+	}
+	return NO_MAIL
+}