@owlmeans/queue 0.1.18-rc.6 → 0.1.18-rc.8

package/src/worker.ts

@@ -0,0 +1,72 @@
+import type { Middleware } from '@owlmeans/context'
+import { MiddlewareStage, MiddlewareType, AppType } from '@owlmeans/context'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import { RouteProtocols } from '@owlmeans/route'
+import type { Config, Context, JobContext, JobEnvelope, JobProcessor, QueueWorkerService } from './types.js'
+import { handleJob } from './bridge.js'
+import { DEFAULT_ALIAS } from './consts.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 elevated 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 || route.protocol !== RouteProtocols.QUEUE) {
+      return
+    }
+    if (route.service != null && route.service !== context.cfg.service) {
+      return
+    }
+    if (entrypoint.handle == null || route.queue == null || !listen.includes(route.queue)) {
+      return
+    }
+
+    served.set(route.queue, [...(served.get(route.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.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export const queueWorkerMiddleware = (alias: string = DEFAULT_ALIAS): Middleware => ({
+  type: MiddlewareType.Context,
+  stage: MiddlewareStage.Ready,
+  apply: async context => {
+    const ctx = context as unknown as Context<Config>
+    if ((ctx.cfg.queue?.listen ?? []).length === 0) {
+      return
+    }
+    if (!ctx.hasService(alias)) {
+      return
+    }
+
+    await ctx.service<QueueWorkerService>(alias).start()
+  }
+})

package/tests/bridge.spec.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from 'bun:test'
+import { assertFresh, requestOf } from '../src/bridge.js'
+import { EnvelopeExpired } from '../src/errors.js'
+import type { JobEnvelope } from '../src/types.js'
+
+const envelope = (enqueuedAt?: string): JobEnvelope => ({
+  alias: 'story:code', params: { id: '7' }, body: { prompt: 'x' }, headers: {}, query: {}, enqueuedAt
+})
+
+describe('rebuilding the request', () => {
+  test('the envelope becomes an ordinary request', () => {
+    const request = requestOf(envelope(), '/story/:id/code')
+
+    expect(request.alias).toBe('story:code')
+    expect(request.params).toEqual({ id: '7' })
+    expect(request.body).toEqual({ prompt: 'x' })
+    expect(request.path).toBe('/story/:id/code')
+  })
+
+  /**
+   * A producer may omit any of the optional parts. The handler on the far side reads them without
+   * 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')
+
+    expect(request.params).toEqual({})
+    expect(request.headers).toEqual({})
+    expect(request.query).toEqual({})
+  })
+})
+
+describe('envelope freshness', () => {
+  test('a fresh envelope passes', () => {
+    expect(() => 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)
+  })
+
+  /**
+   * The window is judged from when the job was ENQUEUED. A job that waited behind a long backlog
+   * was legitimate when it was produced, and judging it on pickup would reject exactly the work a
+   * busy queue delayed — so a generous window has to keep it.
+   */
+  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()
+  })
+
+  test('no configured window means no check', () => {
+    const ancient = new Date(0).toISOString()
+
+    expect(() => assertFresh(envelope(ancient), undefined)).not.toThrow()
+  })
+
+  test('an envelope without a timestamp is not judged', () => {
+    expect(() => assertFresh(envelope(undefined), 60)).not.toThrow()
+  })
+})

package/tests/config.spec.ts

@@ -0,0 +1,66 @@
+import { describe, test, expect } from 'bun:test'
+import { declareQueue, isListening, listenQueues, queueOf, queueOfJob } from '../src/config.js'
+import { UnknownQueue } from '../src/errors.js'
+import type { Config } from '../src/types.js'
+
+const cfg = (): Config => ({ ready: false, service: 'test', type: 'backend' } as unknown as Config)
+
+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'])
+  })
+
+  /**
+   * Declaring runs from a helper that an application may call once per app it composes, so the
+   * second call must not leave two entries under one name — a duplicate would make `queueOf`
+   * answer with whichever happened to be first.
+   */
+  test('re-declaring the same name replaces rather than appends', () => {
+    let config = declareQueue(cfg(), 'work', ['story:code'])
+    config = declareQueue(config, 'work', ['story:code', 'story:gate'])
+
+    expect(config.queue?.queues).toHaveLength(1)
+    expect(queueOf(config, 'work').jobs).toHaveLength(2)
+  })
+
+  test('asking for a queue nobody declared is an error, not undefined', () => {
+    expect(() => queueOf(cfg(), '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()
+  })
+})
+
+describe('listening', () => {
+  /**
+   * Declaring a queue must NOT make this process consume it — that separation is what lets one
+   * binary deploy as a producer in one place and a worker in another.
+   */
+  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(config.queue?.listen ?? []).toHaveLength(0)
+  })
+
+  test('listening is additive and free of duplicates', () => {
+    let config = listenQueues(cfg(), 'work')
+    config = listenQueues(config, 'work', 'ops')
+
+    expect(config.queue?.listen).toEqual(['work', 'ops'])
+    expect(isListening(config, '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'])
+  })
+})

package/tsconfig.json

@@ -10,6 +10,7 @@
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
+    "./tests/**/*",
     "./*.ts"
   ]
 }