@owlmeans/queue 0.1.18-rc.40 → 0.1.18-rc.42

package/src/route.ts

@@ -1,7 +1,7 @@
 import { backend, type RouteDeclaration, type RouteModel, type RouteOptions } from '@owlmeans/route'
-import { UnknownQueue } from './errors.js'
 import { QUEUE_PROTOCOL } from './consts.js'
 import type { QueueRouteOptions } from './types.js'
+import { queueRouteHelper } from './queue-route.js'
 
 /** Declare a backend route carried by a queue. */
 export const job = (
@@ -15,26 +15,9 @@ export const job = (
   return declaration
 }
 
-/** Whether a declaration belongs to the queue transport. */
-export const isQueueRoute = (route: RouteDeclaration | RouteModel): boolean =>
-  ('route' in route ? route.route : route).protocol === QUEUE_PROTOCOL
+/** @deprecated compat:factory-refactor — use `queueRouteHelper.isQueueRoute(…)` */
+export const isQueueRoute = (route: RouteDeclaration | RouteModel): boolean => queueRouteHelper.isQueueRoute(route)
 
-/** Read and validate queue-owned route options. */
-export const queueRouteOptions = (
-  route: RouteDeclaration | RouteModel,
-): Pick<QueueRouteOptions, 'queue' | 'reply'> => {
-  const declaration = 'route' in route ? route.route : route
-  if (declaration.protocol !== QUEUE_PROTOCOL
-    || declaration.protocolOptions == null
-    || typeof declaration.protocolOptions !== 'object') {
-    throw new UnknownQueue(`${declaration.alias}: not a queue protocol`)
-  }
-  const options = declaration.protocolOptions as Record<string, unknown>
-  if (typeof options.queue !== 'string' || options.queue.trim() === '') {
-    throw new UnknownQueue(`${declaration.alias}: route declares no queue`)
-  }
-  if (options.reply != null && typeof options.reply !== 'boolean') {
-    throw new UnknownQueue(`${declaration.alias}: invalid queue reply option`)
-  }
-  return { queue: options.queue, reply: options.reply as boolean | undefined }
-}
+/** @deprecated compat:factory-refactor — use `queueRouteHelper.queueRouteOptions(…)` */
+export const queueRouteOptions = (route: RouteDeclaration | RouteModel): Pick<QueueRouteOptions, 'queue' | 'reply'> =>
+  queueRouteHelper.queueRouteOptions(route)

package/src/transport.ts

@@ -3,7 +3,7 @@ import { type AbstractRequest, type AbstractResponse, type EntrypointTransport,
 import { ResilientError } from '@owlmeans/error'
 import type { Config, Context, JobEnvelope, JobReply, QueueAppend } from './types.js'
 import { DEFAULT_JOB_TIMEOUT, QUEUE_PROTOCOL } from './consts.js'
-import { queueRouteOptions } from './route.js'
+import { queueRouteHelper } from './queue-route.js'
 
 /**
  * The producing half of the bridge: it turns a call on a QUEUE entrypoint into a job, and the
@@ -15,7 +15,7 @@ import { queueRouteOptions } from './route.js'
  * the request rather than from the entrypoint: the far side rebuilds a request, and anything only
  * HTTP understands would not survive the trip anyway.
  */
-export const makeQueueTransport = (alias: string = transportAlias(QUEUE_PROTOCOL)) => {
+export const makeQueueTransport = (alias: string = transportAlias(QUEUE_PROTOCOL)): EntrypointTransport => {
   const location = `queue-transport:${alias}`
 
   const service = createService<EntrypointTransport>(alias, {
@@ -26,7 +26,7 @@ export const makeQueueTransport = (alias: string = transportAlias(QUEUE_PROTOCOL
       const entrypoint = context.entrypoint<CommonEntrypoint>(req.alias)
       const route = entrypoint.route.route
 
-      const { queue, reply: waitsForReply } = queueRouteOptions(route)
+      const { queue, reply: waitsForReply } = queueRouteHelper.queueRouteOptions(route)
 
       const jobs = (context as unknown as QueueAppend).jobs<JobEnvelope, JobReply<T>>(queue)
 

package/src/types.ts

@@ -321,3 +321,6 @@ export interface QueueRouteOptions extends Omit<RouteOptions, 'protocol' | 'prot
   queue: string
   reply?: boolean
 }
+
+/** The context the queue protocol helper is bound to: an app context with the queue appended. */
+export interface QueueContext extends Context<Config>, QueueAppend {}

package/src/worker.ts

@@ -1,53 +1,7 @@
 import type { Middleware } from '@owlmeans/context'
-import { MiddlewareStage, MiddlewareType, AppType } from '@owlmeans/context'
-import type { CommonEntrypoint } from '@owlmeans/entrypoint'
-import type { Config, Context, JobContext, JobEnvelope, JobProcessor, QueueWorkerService } from './types.js'
-import { handleJob } from './bridge.js'
+import { MiddlewareStage, MiddlewareType } from '@owlmeans/context'
+import type { Config, Context, QueueWorkerService } from './types.js'
 import { DEFAULT_ALIAS } from './consts.js'
-import { isQueueRoute, queueRouteOptions } from './route.js'
-
-/**
- * Every queued entrypoint this process both SERVES and LISTENS to, grouped by queue.
- *
- * Both halves are required and they answer different questions. Serving is about code — the alias
- * was bound here, so a handler exists. Listening is about deployment — this process was
- * configured to consume that queue. A worker that bound queues by what it can serve would make
- * every deployment of the same binary a worker for everything it happens to import.
- */
-export const servedJobs = <C extends Config, T extends Context<C>>(
-  context: T
-): Map<string, CommonEntrypoint[]> => {
-  const listen = context.cfg.queue?.listen ?? []
-  const served = new Map<string, CommonEntrypoint[]>()
-
-  context.entrypoints<CommonEntrypoint>().forEach(entrypoint => {
-    const route = entrypoint.route.route
-    if (route.type !== AppType.Backend || !isQueueRoute(route)) {
-      return
-    }
-    if (route.service != null && route.service !== context.cfg.service) {
-      return
-    }
-    const { queue } = queueRouteOptions(route)
-    if (entrypoint.handle == null || !listen.includes(queue)) {
-      return
-    }
-
-    served.set(queue, [...(served.get(queue) ?? []), entrypoint])
-  })
-
-  return served
-}
-
-/**
- * A processor that runs a queued entrypoint call. The driver dispatches by job name, and an
- * entrypoint job's name IS its alias — which is what lets one worker carry both entrypoint jobs
- * and the internal steps an application registers with `process()`.
- */
-export const entrypointProcessor = <C extends Config, T extends Context<C>>(
-  context: T
-): JobProcessor<JobEnvelope, unknown> =>
-  async (job: JobContext<JobEnvelope>) => await handleJob(context, job)
 
 /**
  * Start the worker once the context is ready.

package/tests/bridge.spec.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test'
-import { assertFresh, requestOf } from '../src/bridge.js'
+import { queueBridgeHelper } from '../src/bridge.js'
 import { EnvelopeExpired } from '../src/errors.js'
 import type { JobEnvelope } from '../src/types.js'
 
@@ -9,7 +9,7 @@ const envelope = (enqueuedAt?: string): JobEnvelope => ({
 
 describe('rebuilding the request', () => {
   test('the envelope becomes an ordinary request', () => {
-    const request = requestOf(envelope(), '/story/:id/code')
+    const request = queueBridgeHelper.requestOf(envelope(), '/story/:id/code')
 
     expect(request.alias).toBe('story:code')
     expect(request.params).toEqual({ id: '7' })
@@ -22,7 +22,7 @@ describe('rebuilding the request', () => {
    * checking, so they have to arrive as empty containers rather than as undefined.
    */
   test('absent parts arrive as empty, never undefined', () => {
-    const request = requestOf({ alias: 'story:code' }, '/x')
+    const request = queueBridgeHelper.requestOf({ alias: 'story:code' }, '/x')
 
     expect(request.params).toEqual({})
     expect(request.headers).toEqual({})
@@ -32,13 +32,13 @@ describe('rebuilding the request', () => {
 
 describe('envelope freshness', () => {
   test('a fresh envelope passes', () => {
-    expect(() => assertFresh(envelope(new Date().toISOString()), 60)).not.toThrow()
+    expect(() => queueBridgeHelper.assertFresh(envelope(new Date().toISOString()), 60)).not.toThrow()
   })
 
   test('an envelope older than the window is refused', () => {
     const old = new Date(Date.now() - 120_000).toISOString()
 
-    expect(() => assertFresh(envelope(old), 60)).toThrow(EnvelopeExpired)
+    expect(() => queueBridgeHelper.assertFresh(envelope(old), 60)).toThrow(EnvelopeExpired)
   })
 
   /**
@@ -49,16 +49,16 @@ describe('envelope freshness', () => {
   test('a long wait in the queue is not what expiry is for', () => {
     const enqueued = new Date(Date.now() - 3600_000).toISOString()
 
-    expect(() => assertFresh(envelope(enqueued), 86_400)).not.toThrow()
+    expect(() => queueBridgeHelper.assertFresh(envelope(enqueued), 86_400)).not.toThrow()
   })
 
   test('no configured window means no check', () => {
     const ancient = new Date(0).toISOString()
 
-    expect(() => assertFresh(envelope(ancient), undefined)).not.toThrow()
+    expect(() => queueBridgeHelper.assertFresh(envelope(ancient), undefined)).not.toThrow()
   })
 
   test('an envelope without a timestamp is not judged', () => {
-    expect(() => assertFresh(envelope(undefined), 60)).not.toThrow()
+    expect(() => queueBridgeHelper.assertFresh(envelope(undefined), 60)).not.toThrow()
   })
 })

package/tests/config.spec.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from 'bun:test'
-import { declareQueue, isListening, listenQueues, queueOf, queueOfJob } from '../src/config.js'
+import { declareQueue, listenQueues } from '../src/config.js'
+import { queueConfigOf } from '../src/queue-config.js'
 import { UnknownQueue } from '../src/errors.js'
 import type { Config } from '../src/types.js'
 
@@ -9,7 +10,7 @@ describe('declaring queues', () => {
   test('a declaration records the queue and the jobs it accepts', () => {
     const config = declareQueue(cfg(), 'work', ['story:code', 'story:gate'])
 
-    expect(queueOf(config, 'work').jobs).toEqual(['story:code', 'story:gate'])
+    expect(queueConfigOf(config).queueOf('work').jobs).toEqual(['story:code', 'story:gate'])
   })
 
   /**
@@ -22,18 +23,18 @@ describe('declaring queues', () => {
     config = declareQueue(config, 'work', ['story:code', 'story:gate'])
 
     expect(config.queue?.queues).toHaveLength(1)
-    expect(queueOf(config, 'work').jobs).toHaveLength(2)
+    expect(queueConfigOf(config).queueOf('work').jobs).toHaveLength(2)
   })
 
   test('asking for a queue nobody declared is an error, not undefined', () => {
-    expect(() => queueOf(cfg(), 'missing')).toThrow(UnknownQueue)
+    expect(() => queueConfigOf(cfg()).queueOf('missing')).toThrow(UnknownQueue)
   })
 
   test('a job name resolves back to the queue that accepts it', () => {
     const config = declareQueue(declareQueue(cfg(), 'work', ['story:code']), 'ops', ['files:get'])
 
-    expect(queueOfJob(config, 'files:get')?.name).toBe('ops')
-    expect(queueOfJob(config, 'nothing:declared')).toBeUndefined()
+    expect(queueConfigOf(config).queueOfJob('files:get')?.name).toBe('ops')
+    expect(queueConfigOf(config).queueOfJob('nothing:declared')).toBeUndefined()
   })
 })
 
@@ -45,7 +46,7 @@ describe('listening', () => {
   test('declaring a queue does not make the process listen to it', () => {
     const config = declareQueue(cfg(), 'work', ['story:code'])
 
-    expect(isListening(config, 'work')).toBe(false)
+    expect(queueConfigOf(config).isListening('work')).toBe(false)
     expect(config.queue?.listen ?? []).toHaveLength(0)
   })
 
@@ -54,13 +55,13 @@ describe('listening', () => {
     config = listenQueues(config, 'work', 'ops')
 
     expect(config.queue?.listen).toEqual(['work', 'ops'])
-    expect(isListening(config, 'ops')).toBe(true)
+    expect(queueConfigOf(config).isListening('ops')).toBe(true)
   })
 
   test('listening and declaring do not overwrite each other', () => {
     const config = declareQueue(listenQueues(cfg(), 'work'), 'work', ['story:code'])
 
-    expect(isListening(config, 'work')).toBe(true)
-    expect(queueOf(config, 'work').jobs).toEqual(['story:code'])
+    expect(queueConfigOf(config).isListening('work')).toBe(true)
+    expect(queueConfigOf(config).queueOf('work').jobs).toEqual(['story:code'])
   })
 })

package/tests/protocol.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test'
 import { contract, protocol, schema } from '@owlmeans/entrypoint'
 import { route } from '@owlmeans/route'
 import type { JSONSchemaType } from 'ajv'
-import { enqueueProtocol, job, waitForProtocol, type JobRecord } from '../src/index.js'
+import { job, queueProtocolOf, type JobRecord } from '../src/index.js'
 
 interface Input { value: number }
 interface Output { doubled: number }
@@ -35,23 +35,23 @@ const context = (reply: unknown = { value: { doubled: 6 } }) => {
 describe('protocol-aware queue calls', () => {
   test('derives the broker address and keeps per-call options', async () => {
     const ctx = context()
-    const queued = await enqueueProtocol(ctx as never, declaration, { body: { value: 3 } }, {
+    const queued = await queueProtocolOf(ctx as never).enqueue(declaration, { body: { value: 3 } }, {
       delay: 250, attempts: 3, id: 'projection-1',
     })
     expect(queued.queue).toBe('test')
     expect(ctx.created[0]?.name).toBe(declaration.alias)
     expect(ctx.created[0]?.opts).toEqual({ delay: 250, attempts: 3, id: 'projection-1' })
-    expect(await waitForProtocol(ctx as never, declaration, queued as never)).toEqual({ doubled: 6 })
+    expect(await queueProtocolOf(ctx as never).waitFor(declaration, queued as never)).toEqual({ doubled: 6 })
   })
 
   test('rejects raw aliases and non-queue declarations at runtime', async () => {
-    await expect(enqueueProtocol(context() as never, declaration.alias as never, {} as never)).rejects.toThrow()
+    await expect(queueProtocolOf(context() as never).enqueue(declaration.alias as never, {} as never)).rejects.toThrow()
     const http = protocol(route('test:http', '/http'), contract())
-    await expect(enqueueProtocol(context() as never, http, {})).rejects.toThrow()
+    await expect(queueProtocolOf(context() as never).enqueue(http, {})).rejects.toThrow()
   })
 
   test('rejects a job from another queue or protocol', async () => {
-    await expect(waitForProtocol(context() as never, declaration, {
+    await expect(queueProtocolOf(context() as never).waitFor(declaration, {
       id: 'x', queue: 'other', name: declaration.alias, data: {},
     } as never)).rejects.toThrow()
   })

package/tests/schedule.spec.ts

@@ -1,7 +1,6 @@
 import { describe, test, expect } from 'bun:test'
-import {
-  assertSchedule, assertSchedules, declareQueue, declareSchedule, queueOf, schedulesOf
-} from '../src/config.js'
+import { declareQueue, declareSchedule } from '../src/config.js'
+import { queueConfigOf } from '../src/queue-config.js'
 import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from '../src/errors.js'
 import type { Config, ScheduleDeclaration } from '../src/types.js'
 
@@ -16,23 +15,23 @@ const nightly: ScheduleDeclaration = {
 }
 
 const misdeclared = (schedule: Partial<ScheduleDeclaration>): () => void =>
-  () => assertSchedule(cfg(), { ...nightly, ...schedule } as ScheduleDeclaration)
+  () => queueConfigOf(cfg()).assertSchedule({ ...nightly, ...schedule } as ScheduleDeclaration)
 
 describe('declaring schedules', () => {
   test('a declaration is recorded and read back by its queue', () => {
     const config = declareSchedule(cfg(), nightly)
 
-    expect(schedulesOf(config, 'maintenance')).toEqual([nightly])
-    expect(schedulesOf(config, 'work')).toEqual([])
-    expect(schedulesOf(config)).toHaveLength(1)
+    expect(queueConfigOf(config).schedulesOf('maintenance')).toEqual([nightly])
+    expect(queueConfigOf(config).schedulesOf('work')).toEqual([])
+    expect(queueConfigOf(config).schedulesOf()).toHaveLength(1)
   })
 
   test('re-declaring an id replaces rather than appends', () => {
     let config = declareSchedule(cfg(), nightly)
     config = declareSchedule(config, { ...nightly, pattern: '0 4 * * *' })
 
-    expect(schedulesOf(config)).toHaveLength(1)
-    expect(schedulesOf(config)[0].pattern).toBe('0 4 * * *')
+    expect(queueConfigOf(config).schedulesOf()).toHaveLength(1)
+    expect(queueConfigOf(config).schedulesOf()[0].pattern).toBe('0 4 * * *')
   })
 
   /**
@@ -44,14 +43,14 @@ describe('declaring schedules', () => {
 
     expect(() => declareSchedule(config, { ...nightly, queue: 'missing' })).toThrow(UnknownQueue)
     expect(() => declareSchedule(config, { ...nightly, name: 'story:code' })).toThrow(UnknownJobName)
-    expect(schedulesOf(config)).toHaveLength(0)
+    expect(queueConfigOf(config).schedulesOf()).toHaveLength(0)
   })
 
   test('re-declaring the queue keeps its schedules', () => {
     const config = declareQueue(declareSchedule(cfg(), nightly), 'maintenance', ['reconcile'])
 
-    expect(queueOf(config, 'maintenance').jobs).toEqual(['reconcile'])
-    expect(schedulesOf(config)).toEqual([nightly])
+    expect(queueConfigOf(config).queueOf('maintenance').jobs).toEqual(['reconcile'])
+    expect(queueConfigOf(config).schedulesOf()).toEqual([nightly])
   })
 })
 
@@ -87,7 +86,7 @@ describe('asserting every schedule', () => {
     const config = declareSchedule(cfg(), nightly)
     config.queue?.schedules?.push({ ...nightly, pattern: '0 5 * * *' })
 
-    expect(() => assertSchedules(config)).toThrow(/duplicate/)
+    expect(() => queueConfigOf(config).assertSchedules()).toThrow(/duplicate/)
   })
 
   /** The configuration is plain data; a schedule written into it directly is checked too. */
@@ -95,6 +94,6 @@ describe('asserting every schedule', () => {
     const config = declareSchedule(cfg(), nightly)
     config.queue?.schedules?.push({ id: 'orphan', queue: 'maintenance', name: 'gone', every: 1_000 })
 
-    expect(() => assertSchedules(config)).toThrow(UnknownJobName)
+    expect(() => queueConfigOf(config).assertSchedules()).toThrow(UnknownJobName)
   })
 })

package/build/types.local.d.ts

@@ -1,3 +0,0 @@
-import type { Config, Context, QueueAppend } from './types.js';
-export type QueueContext = Context<Config> & QueueAppend;
-//# sourceMappingURL=types.local.d.ts.map

package/build/types.local.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9D,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,WAAW,CAAA"}

package/build/types.local.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.local.js.map

package/build/types.local.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":""}

package/src/types.local.ts

@@ -1,3 +0,0 @@
-import type { Config, Context, QueueAppend } from './types.js'
-
-export type QueueContext = Context<Config> & QueueAppend