@fabrika/app 0.4.7 → 0.5.0

package/src/testing/kit.ts

@@ -26,6 +26,7 @@ import {
 } from '@fabrika/auth-core'
 import type { Database } from '@fabrika/db'
 import { refuseInProduction } from '@fabrika/db/production'
+import { MemoryEmailSender } from '@fabrika/email/memory'
 import type { FileObjectStore } from '@fabrika/platform'
 import { type IamGateway, REQUEST_ID_HEADER, stripFabrikaCookies } from '@fabrika/proxy-core'
 import { exportJWK, generateKeyPair, SignJWT } from 'jose'
@@ -44,6 +45,7 @@ import { type ConnectFetch, connectVariables } from '../implement/connect'
 import type { SpaAssets } from '../implement/dispatch'
 import type { ApplicationEnvironment, ContractImplementation } from '../implement/implement'
 import type { WorkloadKindOf, WorkloadTokenSource } from '../implement/workload'
+import type { MailKeyScope } from '../jobs/mail'
 import type { HandlerErrorSink } from '../jobs/runner'
 import type { JobRunOptions, JobRunResult } from '../jobs/runner'
 import {
@@ -106,6 +108,13 @@ export interface TestKitOptions {
 	readonly challengeFetch?: ChallengeFetch
 	/** What a job's handler threw, shown on the developer's own machine: `fabrika app dev` sets it, a test need not. */
 	readonly revealHandlerErrors?: HandlerErrorSink
+	/**
+	 * The stand-in for every job's mail transport; a new `MemoryEmailSender` by default. Pass one with other capabilities
+	 * to model another provider: `new MemoryEmailSender({ capabilities: { idempotent: false, confirmation: 'queued' } })`.
+	 * `'none'` models an installation without a transport: `ctx.mail.available` is false, and every send fails
+	 * `mail_not_configured`.
+	 */
+	readonly mail?: MemoryEmailSender | 'none'
 }
 
 export interface TestConnection {
@@ -147,11 +156,21 @@ export interface TestKit<C extends AnyContract> {
 	acceptInvitation(invitationId: string, person?: LabelledTestCaller): LabelledTestCaller
 	/**
 	 * Runs the cron job `name` once, as `fabrika job run <name>` does: under its lease, with the actions IAM signs for
-	 * its key, its writes fenced. It first waits for the runs a form's `then` kicked, so it never races them.
+	 * its key, its writes fenced. It first waits for the runs a form's or a mutation's `then` kicked, so it never races them.
 	 * `FILE_SCAN_JOB` runs the scan of `scan: true` collections with the kit's `scanner`, `FILE_SWEEP_JOB` the sweep of
 	 * removed and orphaned files. Needs the application's data layer on Postgres.
 	 */
 	runJob(name: JobName<C> | typeof FILE_SCAN_JOB | typeof FILE_SWEEP_JOB, options?: JobRunOptions): Promise<JobRunResult>
+	/** Waits for the work requests left running: the runs a form's or a mutation's `then` kicked, a failure's report. */
+	drain(): Promise<void>
+	/**
+	 * The stand-in for every job's transport: what reached it (`accepted`, `handoffs`) and its faults (`refuse`,
+	 * `unavailable`, `unreachable`, `loseAnswers`, `during`, `heal`). Each message carries the transport key,
+	 * `transportMailKey(kit.mailKeyScope, key)`. Under `mail: 'none'` nothing reaches it.
+	 */
+	readonly mail: MemoryEmailSender
+	/** Whose keys this kit's prefix separates: `mailKeyPrefix(kit.mailKeyScope)` is what a job's key gets in front. */
+	readonly mailKeyScope: MailKeyScope
 }
 
 /** The names of the contract's cron jobs. */
@@ -308,6 +327,8 @@ export function bootTestKit<C extends AnyContract>(
 	// issues the proxy's delegation grants.
 	const standIn = options.membership === undefined ? kitMembership(artifact, directoryCallers) : null
 	const membership = options.membership ?? standIn?.rpc
+	const mail = options.mail === undefined || options.mail === 'none' ? new MemoryEmailSender() : options.mail
+	const mailKeyScope: MailKeyScope = Object.freeze({ issuer: TEST_ISSUER, appId })
 	const application: ContractApp = boot(app, {
 		environment: {
 			// The deploy writes the approved contract's digest; the kit's contract is the approved one by definition.
@@ -331,6 +352,7 @@ export function bootTestKit<C extends AnyContract>(
 		membership,
 		connectBindings,
 		workloadTokens,
+		mailStandIn: options.mail === 'none' ? 'none' : mail,
 	})
 
 	let issued = 0
@@ -495,7 +517,7 @@ export function bootTestKit<C extends AnyContract>(
 
 	const proxy = endpointProxy({ artifact, appId, host, iam, issuer: TEST_ISSUER, delegations: membership ?? null })
 
-	// What requests leave running: a job a form's `then` kicked, or a failure's report.
+	// What requests leave running: a job a form's or a mutation's `then` kicked, or a failure's report.
 	const background = new Set<Promise<void>>()
 	const exec: RequestExecutionContext = {
 		waitUntil(promise) {
@@ -550,10 +572,14 @@ export function bootTestKit<C extends AnyContract>(
 		}
 	}
 
-	const runJob = async (name: string, runOptions?: JobRunOptions): Promise<JobRunResult> => {
+	const drain = async (): Promise<void> => {
 		while (background.size > 0) {
 			await Promise.all(background)
 		}
+	}
+
+	const runJob = async (name: string, runOptions?: JobRunOptions): Promise<JobRunResult> => {
+		await drain()
 		return application.jobs.run(name, runOptions)
 	}
 
@@ -578,7 +604,21 @@ export function bootTestKit<C extends AnyContract>(
 		return invitee
 	}
 	return {
-		kit: Object.freeze({ origin, appId, artifact, testCaller, scope, fetch: kitFetch, browser, iam, runJob, acceptInvitation }),
+		kit: Object.freeze({
+			origin,
+			appId,
+			artifact,
+			testCaller,
+			scope,
+			fetch: kitFetch,
+			browser,
+			iam,
+			runJob,
+			drain,
+			acceptInvitation,
+			mail,
+			mailKeyScope,
+		}),
 		standIn,
 		callerOf: (value) => [...memberships.keys()].find((caller) => caller === value),
 	}

package/src/testing/membership.ts

@@ -144,6 +144,8 @@ export interface SentInvitation {
 	readonly role: string
 	readonly scope: Scope
 	readonly expiresAt: number
+	/** When it was last sent, in seconds: when it was opened, or its latest resend. */
+	readonly sentAt: number
 	readonly status: 'open' | 'accepted' | 'cancelled' | 'expired'
 }
 
@@ -165,6 +167,7 @@ interface KitInvitation {
 	readonly role: string
 	readonly email: string
 	readonly expiresAt: number
+	readonly sentAt: number
 	readonly closed: 'cancelled' | 'accepted' | null
 	/** The principal that opened it, whose authority IAM checks again at acceptance; `null` for a seeded one. */
 	readonly inviter: string | null
@@ -479,11 +482,17 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		)
 
 	const openNew = (scope: Scope, role: string, email: string, inviter: string | null): KitInvitation => {
-		const invitation = { id: `invitation-${randomId()}`, scope, role, email, expiresAt: now() + INVITATION_TTL_SECONDS, closed: null, inviter }
+		const sentAt = now()
+		const invitation = { id: `invitation-${randomId()}`, scope, role, email, expiresAt: sentAt + INVITATION_TTL_SECONDS, sentAt, closed: null, inviter }
 		invitations.set(invitation.id, invitation)
 		return invitation
 	}
 
+	const resent = (invitation: KitInvitation): KitInvitation => {
+		const sentAt = now()
+		return { ...invitation, expiresAt: sentAt + INVITATION_TTL_SECONDS, sentAt }
+	}
+
 	/** Spends the request's grant before its binding is compared, as IAM does, so each attempt is single use. */
 	const spend = (caller: TestCaller, input: { delegation: string; requestId: string }, purpose: EndpointDelegation, dimension: string) => {
 		const grant = grants.get(input.delegation)
@@ -595,7 +604,7 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		const invitation = open === undefined
 			? openNew(input.scope, input.role, email, caller.id)
 			: input.invitation?.resend === true
-			? { ...open, expiresAt: now() + INVITATION_TTL_SECONDS }
+			? resent(open)
 			: open
 		invitations.set(invitation.id, invitation)
 		asked.push({
@@ -751,12 +760,13 @@ export function kitMembership(artifact: ContractArtifact, callers: DirectoryCall
 		return link === undefined || link.revoked ? undefined : { id: link.id, mount: link.mount, chain: link.chain }
 	}
 	const invitationsSent = (): readonly SentInvitation[] =>
-		[...invitations.values()].map(({ id, email, role, scope, expiresAt, closed }) => ({
+		[...invitations.values()].map(({ id, email, role, scope, expiresAt, sentAt, closed }) => ({
 			id,
 			email,
 			role,
 			scope,
 			expiresAt,
+			sentAt,
 			status: closed ?? (expiresAt > now() ? 'open' : 'expired'),
 		}))
 	const accept = (invitationId: string, recipient?: TestCaller): AcceptedInvitation => {