@kelpie/server 0.13.0 → 0.14.0

package/src/testing/app.ts

@@ -9,6 +9,7 @@ import type { DatabaseProbe } from '../lib/database.ts'
 import { createCaptureTransport, createLogger } from '../lib/logger.ts'
 import { rateLimitConfigFrom, rateLimitConfigSchema } from '../lib/rateLimit.ts'
 import type { RateLimitConfig } from '../lib/rateLimit.ts'
+import type { JobRegistry } from '../lib/jobs.ts'
 import type { KelpieModule } from '../runtime/module.ts'
 import type { ModuleContributions } from '../runtime/registry.ts'
 import type { EntitlementRegistry } from '../runtime/entitlements.ts'
@@ -69,6 +70,12 @@ export interface TestAppOptions {
   readonly signupsEnabled?: boolean
   /** Reported through `GET /v1/public/config`. Defaults to `[]`. */
   readonly regions?: readonly PublicRegion[]
+  /**
+   * Jobs registry to hand each module at register time. Optional: tests that
+   * never define a job (the common case) leave this unset, and a stub
+   * refuses `define` with a boot-time bug message that names the module.
+   */
+  readonly jobs?: JobRegistry
 }
 
 export interface TestApp {
@@ -102,6 +109,7 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     ...(options.entitlements === undefined ? {} : { entitlements: options.entitlements }),
     ...(options.moduleConfig === undefined ? {} : { moduleConfig: options.moduleConfig }),
     ...(options.resolveActor === undefined ? {} : { resolveActor: options.resolveActor }),
+    ...(options.jobs === undefined ? {} : { jobs: options.jobs }),
     services: {
       ...services,
       ...(options.signupsEnabled === undefined ? {} : { signupsEnabled: options.signupsEnabled }),

package/src/testing/database.ts

@@ -6,6 +6,8 @@ import { connectDatabase } from '../lib/database.ts'
 import type { DatabaseConnection } from '../lib/database.ts'
 import { createLogger } from '../lib/logger.ts'
 import { coreModules } from '../modules/core.ts'
+import { createJobsRuntime } from '../runtime/jobs.ts'
+import type { JobsRuntime } from '../runtime/jobs.ts'
 import { runMigrations } from '../runtime/migrate.ts'
 import { registerModules } from '../runtime/registry.ts'
 import { TEST_ENVIRONMENT } from './environment.ts'
@@ -30,6 +32,12 @@ const silentLogger = createLogger({ level: 'error', transports: [] })
 export interface TestDatabase extends DatabaseConnection {
   /** Empties every table. Cheaper than truncating or re-migrating between tests. */
   readonly truncateAll: () => Promise<void>
+  /**
+   * The pg-boss-backed jobs runtime, migrated onto the same test database.
+   * Tests that need workers running call `jobs.startWorking()`; tests that
+   * only enqueue can leave it stopped, since `enqueueOnTx` needs no worker.
+   */
+  readonly jobs: JobsRuntime
 }
 
 /**
@@ -90,18 +98,28 @@ export async function connectTestDatabase(connectionString: string): Promise<Tes
   await ensureDatabaseExists(connectionString)
 
   const connection = connectDatabase(connectionString, silentLogger)
-  const services = createTestServices({ db: connection.db })
+  const jobs = createJobsRuntime({
+    connectionString,
+    logger: silentLogger,
+    // A short poll floor so a test that enqueues and waits for the handler
+    // never blocks on the 30 s NOTIFY backstop when notify is unavailable
+    // (e.g. connection dropped between tests). Real workers stay at 30 s.
+    pollingIntervalSeconds: 0.5,
+  })
+  const services = createTestServices({ db: connection.db, enqueueOnTx: jobs.enqueueOnTx })
   const contributions = await registerModules({
     modules: coreModules,
     // Enough for core modules to configure themselves; no test reads it further.
     environment: TEST_ENVIRONMENT,
     logger: silentLogger,
     services,
+    jobs: jobs.registry,
     email: { provider: TEST_EMAIL_PROVIDER, from: TEST_EMAIL_FROM },
     additionalEmailProviders: new Map([[TEST_EMAIL_PROVIDER, services.emailSender]]),
   })
 
   await runMigrations(connection.db, contributions.schemas, silentLogger)
+  await jobs.migrate()
 
   let cachedReset: string | undefined
 
@@ -189,7 +207,22 @@ export async function connectTestDatabase(connectionString: string): Promise<Tes
     if (cachedReset !== undefined) {
       await connection.db.execute(sql.raw(cachedReset))
     }
+
+    // Clear pg-boss's job table too. Every test starts with an empty queue
+    // regardless of whether the previous test's worker consumed everything.
+    // A TRUNCATE would rebuild the partition heap on every call; delete stays
+    // fast against a mostly-empty table.
+    await connection.db.execute(sql`delete from pgboss.job`)
+  }
+
+  async function close(): Promise<void> {
+    // Order matters: pg-boss owns its own connection pool, so stop it first
+    // so it can `unlisten` and drain workers. Then close the postgres.js pool
+    // the app uses. Idempotent for tests that never started the worker;
+    // `jobs.stop()` returns early when nothing is running.
+    await jobs.stop()
+    await connection.close()
   }
 
-  return { ...connection, truncateAll }
+  return { ...connection, close, truncateAll, jobs }
 }

package/src/testing/services.ts

@@ -9,6 +9,7 @@ import { createEventBus } from '../runtime/events.ts'
 import type { EventBus } from '../runtime/events.ts'
 import type { ModuleServices } from '../runtime/module.ts'
 import { createTransactionScope } from '../runtime/transaction.ts'
+import type { EnqueueOnTransaction } from '../runtime/transaction.ts'
 
 /**
  * The collaborators a module needs, wired for tests.
@@ -40,6 +41,12 @@ export interface TestServicesOptions {
   readonly appBaseUrl?: string
   /** Threaded through to `ModuleServices.secretEncryption`, so a test exercises the preferred path. */
   readonly secretEncryption?: SecretEncryptionConfig
+  /**
+   * How `tx.jobs.enqueue(...)` reaches its backing runtime. Omitted, the
+   * transaction scope rejects the call with a boot-time bug message; tests
+   * that never enqueue leave this unset.
+   */
+  readonly enqueueOnTx?: EnqueueOnTransaction
 }
 
 export interface TestServices extends ModuleServices {
@@ -81,7 +88,14 @@ export function createTestServices(options: TestServicesOptions = {}): TestServi
 
   return {
     db,
-    transaction: createTransactionScope({ db, bus: events, logger, createId, now }),
+    transaction: createTransactionScope({
+      db,
+      bus: events,
+      logger,
+      createId,
+      now,
+      ...(options.enqueueOnTx === undefined ? {} : { enqueueOnTx: options.enqueueOnTx }),
+    }),
     createId,
     now,
     emailSender: sender,

package/src/worker.ts

@@ -0,0 +1,20 @@
+import type { AssemblyBoot } from './boot.ts'
+
+/**
+ * Runs after `bootAssembly` on the worker entry point.
+ *
+ * Applies pg-boss's schema (idempotent), opens the persistent pg-boss
+ * instance, and starts the work loop for every registered handle. Does not
+ * call `createApp`: workers process queues, they do not answer HTTP.
+ *
+ * The API entry point calls the same steps unless started with `--no-worker`,
+ * so an OSS assembly runs one container that both serves and works. Cloud
+ * runs a separate worker process group and passes `--no-worker` to the API,
+ * so the two never contend on the same handler.
+ */
+export async function startWorker(boot: AssemblyBoot): Promise<void> {
+  await boot.jobs.migrate()
+  await boot.jobs.start()
+  await boot.jobs.startWorking()
+  boot.logger.info('worker started', { runtimeMode: boot.config.runtimeMode })
+}