@kelpie/server 0.5.1 → 0.6.0

package/src/runtime/registry.ts

@@ -4,6 +4,8 @@ import type { Context, Handler, MiddlewareHandler } from 'hono'
 import type { Actor } from '../lib/actor.ts'
 import { requireWorkspaceId } from '../lib/actor.ts'
 import type { Environment } from '../lib/config.ts'
+import { createLogEmailSender } from '../lib/email.ts'
+import type { EmailMessage, EmailSender } from '../lib/email.ts'
 import { AppError, describeThrown, describeValidationIssue, toErrorDetails } from '../lib/errors.ts'
 import type { Logger } from '../lib/logger.ts'
 import { createEntitlementRegistry, requireCapability } from './entitlements.ts'
@@ -103,6 +105,28 @@ export interface ModuleRuntimeOptions {
   readonly entitlements?: EntitlementRegistry | undefined
   /** The database, transaction scope, and collaborators every module builds on. */
   readonly services: ModuleServices
+  /**
+   * Picks the transactional-mail provider. `provider` is a name a module
+   * registered via `context.provideEmailSender(name, sender)`. `'log'` is a
+   * built-in the runtime always registers using its own logger and `from`, so
+   * a bare install boots without a provider module.
+   *
+   * `from` is the address on every outgoing message. The log provider uses it
+   * verbatim; other providers may read the same value through their own
+   * `context.config` if they need to.
+   */
+  readonly email: {
+    readonly provider: string
+    readonly from: string
+  }
+  /**
+   * Extra named providers seeded into the registry before any module runs.
+   * Modules still register through `context.provideEmailSender`; these are for
+   * tests that want to inspect what was sent without building a whole module.
+   * A name collision with a module (or with `'log'`) fails boot exactly as if
+   * two modules had registered it.
+   */
+  readonly additionalEmailProviders?: ReadonlyMap<string, EmailSender> | undefined
   /**
    * The deploy-time module override (`lib/moduleConfig.ts`), parsed. A locked
    * module id wins over whatever a workspace's own settings say.
@@ -132,6 +156,45 @@ interface Accumulator {
   readonly mcpTools: McpTool[]
 }
 
+/**
+ * The email sender every module writes through. `target` is set once, after
+ * all modules have registered, from the provider `email.provider` picked. Until
+ * then a `.send()` throws: consumer modules capture the proxy at register time
+ * but only reach it at request time, so this is unreachable in normal flow.
+ */
+class EmailSenderProxy implements EmailSender {
+  private target: EmailSender | undefined = undefined
+
+  setTarget(sender: EmailSender): void {
+    this.target = sender
+  }
+
+  send(message: EmailMessage): Promise<void> {
+    if (this.target === undefined) {
+      return Promise.reject(
+        new Error('email sender used before boot resolved a provider. Set email.provider in kelpie.config.ts.'),
+      )
+    }
+
+    return this.target.send(message)
+  }
+}
+
+/**
+ * The name the runtime uses for its built-in log sender. Reserved: a module
+ * that tries to register under this name fails boot.
+ */
+const LOG_PROVIDER_NAME = 'log'
+
+/**
+ * Records which module registered a given provider name, so a collision error
+ * can name both parties. `build` is invoked once, only for the chosen provider.
+ */
+interface RegisteredProvider {
+  readonly build: () => EmailSender
+  readonly registeredBy: string
+}
+
 function createModuleContext(
   module: KelpieModule,
   accumulator: Accumulator,
@@ -139,9 +202,30 @@ function createModuleContext(
   events: EventBus,
   entitlements: EntitlementRegistry,
   moduleCatalog: readonly ModuleCatalogEntry[],
+  emailProxy: EmailSenderProxy,
+  providers: Map<string, RegisteredProvider>,
 ): ModuleContext {
   return {
     ...options.services,
+    email: emailProxy,
+
+    provideEmailSender(name, build) {
+      if (name === LOG_PROVIDER_NAME) {
+        throw new ModuleBootError([
+          `module "${module.id}" registers email provider "${name}", which is reserved by the runtime`,
+        ])
+      }
+
+      const existing = providers.get(name)
+
+      if (existing !== undefined) {
+        throw new ModuleBootError([
+          `module "${module.id}" registers email provider "${name}", but module "${existing.registeredBy}" already did`,
+        ])
+      }
+
+      providers.set(name, { build, registeredBy: module.id })
+    },
 
     routes(mount) {
       const router = new Hono()
@@ -262,6 +346,33 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
 
   const events = options.events ?? createEventBus(options.logger)
   const entitlements = options.entitlements ?? createEntitlementRegistry()
+  const emailProxy = new EmailSenderProxy()
+  const emailProviders = new Map<string, RegisteredProvider>()
+
+  // The built-in log provider is always available, no module required. Named
+  // 'log' in kelpie.config.ts's email.provider picks this one. Built eagerly
+  // because it has no env to parse and never fails.
+  const logSender = createLogEmailSender(options.logger, options.email.from)
+
+  emailProviders.set(LOG_PROVIDER_NAME, {
+    build: () => logSender,
+    registeredBy: '<runtime>',
+  })
+
+  // Seed test-supplied providers before any module registers, so a module
+  // collision with one of them fails boot the same way two modules would.
+  if (options.additionalEmailProviders !== undefined) {
+    for (const [name, sender] of options.additionalEmailProviders) {
+      if (emailProviders.has(name)) {
+        throw new ModuleBootError([
+          `additionalEmailProviders names "${name}", which is already registered by the runtime`,
+        ])
+      }
+
+      emailProviders.set(name, { build: () => sender, registeredBy: '<additionalEmailProviders>' })
+    }
+  }
+
   const accumulator: Accumulator = {
     routers: [],
     publicRouters: [],
@@ -295,8 +406,30 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
     entitlements.provide(createModuleConfigProvider(options.moduleConfig))
   }
 
+  // Register every module's event catalog before any `register` runs, so a
+  // module that subscribes to another module's event during its own registration
+  // finds a validated name.
   for (const module of ordered) {
-    const context = createModuleContext(module, accumulator, options, events, entitlements, moduleCatalog)
+    if (module.events !== undefined) {
+      try {
+        events.registerCatalog({ moduleId: module.id, events: module.events })
+      } catch (error: unknown) {
+        throw new ModuleBootError([describeThrown(error)], { cause: error })
+      }
+    }
+  }
+
+  for (const module of ordered) {
+    const context = createModuleContext(
+      module,
+      accumulator,
+      options,
+      events,
+      entitlements,
+      moduleCatalog,
+      emailProxy,
+      emailProviders,
+    )
 
     try {
       await module.register(context)
@@ -313,9 +446,44 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
     context.log.debug('module registered')
   }
 
+  // Resolve the configured provider. The lookup happens after every module has
+  // registered, so a module registering a provider late in the list still wins
+  // if the config names it. An unknown name is a boot error whose message lists
+  // every registered name, so a self-hoster sees what they had to pick from.
+  const chosen = emailProviders.get(options.email.provider)
+
+  if (chosen === undefined) {
+    const available = [...emailProviders.keys()].sort()
+
+    throw new ModuleBootError([
+      `email.provider is "${options.email.provider}", which no module registered. Available: ${available.join(', ')}`,
+    ])
+  }
+
+  // Only the chosen provider is built. A registered-but-unused provider never
+  // runs its factory, so a self-hoster who leaves a module in `modules:` but
+  // picks a different provider is not asked for the unused module's env.
+  let chosenSender: EmailSender
+
+  try {
+    chosenSender = chosen.build()
+  } catch (error: unknown) {
+    if (error instanceof ModuleBootError) {
+      throw error
+    }
+
+    throw new ModuleBootError(
+      [`email provider "${options.email.provider}" (${chosen.registeredBy}) failed to build: ${describeThrown(error)}`],
+      { cause: error },
+    )
+  }
+
+  emailProxy.setTarget(chosenSender)
+
   options.logger.info('modules registered', {
     count: ordered.length,
     ids: ordered.map((module) => module.id),
+    emailProvider: options.email.provider,
   })
 
   return {

package/src/runtime/transaction.ts

@@ -1,6 +1,10 @@
+import type { EventActor, EventTarget, KelpieEvent } from '@kelpie/schemas'
+
 import type { Database } from '../lib/database.ts'
+import type { IdFactory } from '../lib/ids.ts'
 import type { Logger } from '../lib/logger.ts'
-import type { DomainEventName, DomainEvents, EventBus } from './events.ts'
+import { checkEventCycle, currentEventChain } from './events.ts'
+import type { EventBus, EventName, KelpieEventMap } from './events.ts'
 
 /**
  * One service call, one transaction, per `architecture.md`.
@@ -19,9 +23,21 @@ export type Transaction = Parameters<Parameters<Database['transaction']>[0]>[0]
  */
 export type Queryable = Database | Transaction
 
-/** Collects events during the transaction. Nothing leaves until commit. */
+type EventMapFor<Name extends EventName> = keyof KelpieEventMap extends never
+  ? unknown
+  : Name extends keyof KelpieEventMap
+    ? KelpieEventMap[Name]
+    : unknown
+
+/**
+ * Collects events during the transaction. Nothing leaves until commit.
+ *
+ * `emit` stamps the envelope (id, workspaceId, actor, occurredAt, causedBy) so
+ * services pass only what they know: the name, the target the event refers to,
+ * and the module-defined payload.
+ */
 export interface BufferedEvents {
-  emit<Name extends DomainEventName>(name: Name, payload: DomainEvents[Name]): void
+  emit<Name extends EventName>(name: Name, target: EventTarget, data: EventMapFor<Name>): void
 }
 
 export interface TransactionContext {
@@ -29,48 +45,100 @@ export interface TransactionContext {
   readonly events: BufferedEvents
 }
 
+export interface TransactionOptions {
+  /**
+   * The tenant this work belongs to. Every event emitted from the scope stamps
+   * it into the envelope. Required when any event is emitted; a scope that
+   * emits nothing may omit it.
+   */
+  readonly workspaceId?: string
+  /** Who caused this work. Defaults to `system`. */
+  readonly actor?: EventActor
+}
+
 /** Runs `work` in one transaction and publishes its events after commit. */
 export type TransactionScope = <Result>(
   work: (context: TransactionContext) => Promise<Result>,
+  options?: TransactionOptions,
 ) => Promise<Result>
 
-/**
- * A buffered event keeps its publication as a closure. The name and payload were
- * correlated at the `emit` call site; storing them as a pair would lose that and
- * force a cast at publication.
- */
 interface BufferedEvent {
-  readonly name: DomainEventName
-  readonly publish: () => Promise<void>
+  readonly name: string
+  readonly envelope: KelpieEvent<string, unknown>
 }
 
+const SYSTEM_ACTOR: EventActor = { kind: 'system' }
+
 export interface TransactionScopeDependencies {
   readonly db: Database
   readonly bus: EventBus
   readonly logger: Logger
+  readonly createId: IdFactory
+  /** Injected so a test can pin timestamps. Defaults to `Date.now`. */
+  readonly now?: () => Date
+  /** Chain-depth cap. Reads `KELPIE_EVENT_MAX_DEPTH`; otherwise 8. */
+  readonly maxDepth?: number
 }
 
 export function createTransactionScope(dependencies: TransactionScopeDependencies): TransactionScope {
-  return async function runInTransaction(work) {
+  const now = dependencies.now ?? ((): Date => new Date())
+  const maxDepth = dependencies.maxDepth ?? readMaxDepthFromEnv() ?? 8
+
+  return async function runInTransaction(work, options) {
+    const actor = options?.actor ?? SYSTEM_ACTOR
+    const workspaceId = options?.workspaceId
     const buffered: BufferedEvent[] = []
 
     const result = await dependencies.db.transaction((tx) =>
       work({
         tx,
         events: {
-          emit(name, payload) {
-            buffered.push({ name, publish: () => dependencies.bus.publish(name, payload) })
+          emit(name, target, data) {
+            if (workspaceId === undefined || workspaceId.length === 0) {
+              throw new Error(
+                `event "${name}" was emitted without a workspaceId: pass it via TransactionOptions`,
+              )
+            }
+
+            const chain = currentEventChain()
+            const outcome = checkEventCycle(chain, name, target, maxDepth)
+
+            if (outcome.kind !== 'ok') {
+              dependencies.logger.error('event cycle guard dropped emit', {
+                event: name,
+                target,
+                reason: outcome.kind,
+                chain: chain.map((entry) => ({
+                  id: entry.id,
+                  name: entry.name,
+                  target: { type: entry.targetType, id: entry.targetId },
+                })),
+              })
+              return
+            }
+
+            const envelope: KelpieEvent<string, unknown> = {
+              id: dependencies.createId('event'),
+              name,
+              workspaceId,
+              actor,
+              occurredAt: now().toISOString(),
+              target,
+              ...(chain.length > 0 ? { causedBy: chain[chain.length - 1]!.id } : {}),
+              data: data as unknown,
+            }
+
+            buffered.push({ name, envelope })
           },
         },
       }),
     )
 
     // Past this line the transaction has committed. Publishing is deliberately
-    // not awaited: the webhooks engine is a consumer, and an outbound HTTP
-    // delivery must not sit inside the request that triggered it. Tests and
-    // graceful shutdown wait via `bus.drain()`.
+    // not awaited: an outbound HTTP delivery must not sit inside the request
+    // that triggered it. Tests and graceful shutdown wait via `bus.drain()`.
     for (const event of buffered) {
-      void event.publish().catch((error: unknown) => {
+      void dependencies.bus.publish(event.envelope as never).catch((error: unknown) => {
         dependencies.logger.error('event publication failed', { event: event.name, error })
       })
     }
@@ -78,3 +146,12 @@ export function createTransactionScope(dependencies: TransactionScopeDependencie
     return result
   }
 }
+
+function readMaxDepthFromEnv(): number | undefined {
+  const raw = process.env.KELPIE_EVENT_MAX_DEPTH
+  if (raw === undefined || raw === '') {
+    return undefined
+  }
+  const parsed = Number.parseInt(raw, 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}

package/src/testing/app.ts

@@ -5,7 +5,7 @@ import type { AppBindings } from '../app.ts'
 import type { Actor } from '../lib/actor.ts'
 import type { Environment } from '../lib/config.ts'
 import type { DatabaseProbe } from '../lib/database.ts'
-import { createLogger } from '../lib/logger.ts'
+import { createCaptureTransport, createLogger } from '../lib/logger.ts'
 import { rateLimitConfigFrom, rateLimitConfigSchema } from '../lib/rateLimit.ts'
 import type { RateLimitConfig } from '../lib/rateLimit.ts'
 import type { KelpieModule } from '../runtime/module.ts'
@@ -13,7 +13,7 @@ import type { ModuleContributions } from '../runtime/registry.ts'
 import type { EntitlementRegistry } from '../runtime/entitlements.ts'
 import { registerModules } from '../runtime/registry.ts'
 import { TEST_ENVIRONMENT } from './environment.ts'
-import { createTestServices } from './services.ts'
+import { TEST_EMAIL_FROM, TEST_EMAIL_PROVIDER, createTestServices } from './services.ts'
 import type { TestServices } from './services.ts'
 
 /** The same defaults `loadConfig` produces from an empty environment: one source of numbers for both. */
@@ -71,14 +71,22 @@ const reachableDatabase = (): Promise<DatabaseProbe> => Promise.resolve({ reacha
 
 export async function createTestApp(options: TestAppOptions = {}): Promise<TestApp> {
   const logLines: string[] = []
-  const logger = createLogger('debug', (line) => logLines.push(line))
+  const logger = createLogger({
+    level: 'debug',
+    transports: [createCaptureTransport((line) => logLines.push(line))],
+  })
 
   const services = options.services ?? createTestServices()
+  // Seed the test collecting sender under a stable name and point the email
+  // config at it. A test that wants a real provider module in the mix registers
+  // it as usual; picking that name in `email.provider` overrides this default.
   const contributions = await registerModules({
     modules: options.modules ?? [],
     environment: options.environment ?? TEST_ENVIRONMENT,
     logger,
     events: services.events,
+    email: { provider: TEST_EMAIL_PROVIDER, from: TEST_EMAIL_FROM },
+    additionalEmailProviders: new Map([[TEST_EMAIL_PROVIDER, services.emailSender]]),
     ...(options.entitlements === undefined ? {} : { entitlements: options.entitlements }),
     ...(options.moduleConfig === undefined ? {} : { moduleConfig: options.moduleConfig }),
     ...(options.resolveActor === undefined ? {} : { resolveActor: options.resolveActor }),

package/src/testing/database.ts

@@ -9,7 +9,7 @@ import { coreModules } from '../modules/core.ts'
 import { runMigrations } from '../runtime/migrate.ts'
 import { registerModules } from '../runtime/registry.ts'
 import { TEST_ENVIRONMENT } from './environment.ts'
-import { createTestServices } from './services.ts'
+import { TEST_EMAIL_FROM, TEST_EMAIL_PROVIDER, createTestServices } from './services.ts'
 
 /**
  * A migrated database for integration tests.
@@ -20,7 +20,7 @@ import { createTestServices } from './services.ts'
  * magnitude faster and just as isolated.
  */
 
-const silentLogger = createLogger('error', () => undefined)
+const silentLogger = createLogger({ level: 'error', transports: [] })
 
 export interface TestDatabase extends DatabaseConnection {
   /** Empties every table. Cheaper than re-running migrations between tests. */
@@ -72,12 +72,15 @@ export async function connectTestDatabase(connectionString: string): Promise<Tes
   await ensureDatabaseExists(connectionString)
 
   const connection = connectDatabase(connectionString, silentLogger)
+  const services = createTestServices({ db: connection.db })
   const contributions = await registerModules({
     modules: coreModules,
     // Enough for core modules to configure themselves; no test reads it further.
     environment: TEST_ENVIRONMENT,
     logger: silentLogger,
-    services: createTestServices({ db: connection.db }),
+    services,
+    email: { provider: TEST_EMAIL_PROVIDER, from: TEST_EMAIL_FROM },
+    additionalEmailProviders: new Map([[TEST_EMAIL_PROVIDER, services.emailSender]]),
   })
 
   await runMigrations(connection.db, contributions.schemas, silentLogger)

package/src/testing/services.ts

@@ -4,6 +4,7 @@ import type { EmailMessage, EmailSender } from '../lib/email.ts'
 import { createIdFactory } from '../lib/ids.ts'
 import type { IdFactory } from '../lib/ids.ts'
 import { createLogger } from '../lib/logger.ts'
+import type { SecretEncryptionConfig } from '../lib/secrets.ts'
 import { createEventBus } from '../runtime/events.ts'
 import type { EventBus } from '../runtime/events.ts'
 import type { ModuleServices } from '../runtime/module.ts'
@@ -20,14 +21,35 @@ import { createTransactionScope } from '../runtime/transaction.ts'
 /** Never queried. A unit test that reaches the database fails here, loudly. */
 const UNUSED_DATABASE_URL = 'postgres://unused:unused@127.0.0.1:1/unused'
 
+/**
+ * The provider name `createTestApp` seeds and points `email.provider` at.
+ * Exported so a test spawning `registerModules` directly can pass the same
+ * name and reach the same collecting sender.
+ */
+export const TEST_EMAIL_PROVIDER = 'test'
+
+/** The from address the test email config uses. Arbitrary but real. */
+export const TEST_EMAIL_FROM = 'kelpie-test@example.com'
+
 export interface TestServicesOptions {
   readonly db?: Database
   readonly now?: () => Date
   readonly createId?: IdFactory
   readonly events?: EventBus
+  /** Threaded through to `ModuleServices.appBaseUrl`, so a test exercises the preferred path. */
+  readonly appBaseUrl?: string
+  /** Threaded through to `ModuleServices.secretEncryption`, so a test exercises the preferred path. */
+  readonly secretEncryption?: SecretEncryptionConfig
 }
 
 export interface TestServices extends ModuleServices {
+  /**
+   * The collecting sender `createTestApp` seeds under `TEST_EMAIL_PROVIDER`.
+   * `services.emailSender` (this field) is what actually receives calls; a
+   * consumer module reaches it through `context.email`, which the runtime's
+   * proxy points at whichever provider `email.provider` picked.
+   */
+  readonly emailSender: EmailSender
   /** Everything the email port was asked to send, in order. */
   readonly sentEmails: readonly EmailMessage[]
   readonly events: EventBus
@@ -50,18 +72,25 @@ function createCollectingEmailSender(): { sender: EmailSender; sent: EmailMessag
 }
 
 export function createTestServices(options: TestServicesOptions = {}): TestServices {
-  const logger = createLogger('error', () => undefined)
+  const logger = createLogger({ level: 'error', transports: [] })
   const db = options.db ?? connectDatabase(UNUSED_DATABASE_URL, logger).db
   const events = options.events ?? createEventBus(logger)
+  const createId = options.createId ?? createIdFactory()
+  const now = options.now ?? ((): Date => new Date())
   const { sender, sent } = createCollectingEmailSender()
 
   return {
     db,
-    transaction: createTransactionScope({ db, bus: events, logger }),
-    email: sender,
-    createId: options.createId ?? createIdFactory(),
-    now: options.now ?? ((): Date => new Date()),
+    transaction: createTransactionScope({ db, bus: events, logger, createId, now }),
+    createId,
+    now,
+    emailSender: sender,
     sentEmails: sent,
     events,
+    // Spread conditionally so the field is absent (not `undefined`) when the
+    // caller does not opt in, keeping the fallback path (context.config) live
+    // for the many suites that never touch these fields.
+    ...(options.appBaseUrl === undefined ? {} : { appBaseUrl: options.appBaseUrl }),
+    ...(options.secretEncryption === undefined ? {} : { secretEncryption: options.secretEncryption }),
   }
 }