From cd2a0e6533dc5fb50f30f33ee96551a884ea467a Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 15:58:03 -0600 Subject: [PATCH 1/7] Add an optional worker health snapshot adapter --- docs/worker-health-adapter.md | 35 +++++ models/Telemetry/WorkerHealthAdapter.cfc | 39 +++++ tests/specs/unit/WorkerHealthAdapterSpec.cfc | 150 +++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 docs/worker-health-adapter.md create mode 100644 models/Telemetry/WorkerHealthAdapter.cfc create mode 100644 tests/specs/unit/WorkerHealthAdapterSpec.cfc diff --git a/docs/worker-health-adapter.md b/docs/worker-health-adapter.md new file mode 100644 index 0000000..94d0f2b --- /dev/null +++ b/docs/worker-health-adapter.md @@ -0,0 +1,35 @@ +# Worker health snapshot adapter + +`WorkerHealthAdapter@cbq` provides read-only snapshots of a registered cbq worker pool. It does not start workers, poll the queue provider, publish metrics or depend on Sentry. Each call resolves the pool again, so it follows the current registered pool rather than caching a stale instance. + +For Sentry automatic collection, select the adapter explicitly: + +```cfml +moduleSettings.sentry.automaticCollectors = { + enabled: true, + queueWorkers: [ { + // Fixed metric label; this does not choose a pool. + name: "mail", + // Provider-owned snapshot implementation; other queue providers use their own adapters. + adapter: "WorkerHealthAdapter@cbq", + // Explicit cbq pool selection. No default pool is assumed. + options: { pool: "outbound" } + } ] +}; +``` + +Sentry also needs its existing valid DSN and `enableMetrics:true` settings. No Sentry setting or dependency is needed to use the snapshot directly: + +```cfml +snapshot = wirebox.getInstance( "WorkerHealthAdapter@cbq" ) + .sample( { options: { pool: "outbound" } } ); +// Or samplePool(workerPool) when the caller already has the pool instance. +``` + +The adapter follows the optional `ISnapshotAdapter.sample(context)` contract structurally; it does not import Sentry's interface. `options.pool` must be supplied explicitly. Missing configuration or an unregistered pool throws an error so the caller can record a failed sample rather than a false zero. + +Snapshots contain `configuredWorkers` from pool quantity and `activeExecutions` only when the executor advertises `features.taskMethods` and reports `activeCount`. Configured concurrency and current executor capacity are not active worker counts. ColdBox versions or executor types without supported activity statistics omit `activeExecutions`; an unstarted executor also leaves it absent. A measured idle executor can report zero. The snapshot does not manufacture a worker heartbeat, retry totals, queue backlog, job identifiers or payload data. + +Local verification and release requirements are recorded with the companion Sentry change. This adapter must be present in the installed cbq version before configuring its mapping in Sentry; it is not included in older cbq releases. + +Local checks passed on prepared Lucee 5.4.8.2, BoxLang 1.18.0+66 and Adobe 2023 update 25 runtimes (Java 21): 6/6 adapter specs and 134/134 companion Sentry specs per engine, with zero failures/errors/skips. The latter includes ten PostgreSQL 18.1 cases with actual cbq workers, including automatic WireBox resolution of this adapter and idle/busy worker activity. cbq source was `next` base `fad884a` plus this adapter; qb 14.1.0, ColdBox 7.5.2 and TestBox 3.2 were supplied by the isolated Sentry harness. The complete cbq suite was not run locally. This does not qualify crash recovery, actual worker heartbeats, other queue providers or real Sentry delivery/indexing. diff --git a/models/Telemetry/WorkerHealthAdapter.cfc b/models/Telemetry/WorkerHealthAdapter.cfc new file mode 100644 index 0000000..2bf6254 --- /dev/null +++ b/models/Telemetry/WorkerHealthAdapter.cfc @@ -0,0 +1,39 @@ +/** Read-only worker snapshots. Compatible with Sentry's sample(context) contract; Sentry is not required. */ +component { + + property name="config" inject="Config@cbq"; + + struct function sample( required struct context ) { + if ( + !arguments.context.keyExists( "options" ) || !isStruct( arguments.context.options ) || + !arguments.context.options.keyExists( "pool" ) || isNull( arguments.context.options.pool ) || !isSimpleValue( + arguments.context.options.pool + ) || + !len( trim( arguments.context.options.pool ) ) + ) { + throw( + type = "cbq.Telemetry.MissingWorkerPool", + message = "Configure options.pool explicitly for the worker health adapter." + ); + } + return samplePool( variables.config.getWorkerPool( arguments.context.options.pool ) ); + } + + struct function samplePool( required any pool ) { + var snapshot = { "configuredWorkers" : arguments.pool.getQuantity() }; + try { + var stats = arguments.pool.getExecutor().getStats(); + // Some executors return a fallback zero when activity cannot be measured. + if ( + stats.keyExists( "features" ) && stats.features.keyExists( "taskMethods" ) && stats.features.taskMethods && + stats.keyExists( "activeCount" ) + ) { + snapshot[ "activeExecutions" ] = stats.activeCount; + } + } catch ( any unavailable ) { + // An unstarted/unsupported executor does not imply zero activity or a worker heartbeat. + } + return snapshot; + } + +} diff --git a/tests/specs/unit/WorkerHealthAdapterSpec.cfc b/tests/specs/unit/WorkerHealthAdapterSpec.cfc new file mode 100644 index 0000000..0cfe1f3 --- /dev/null +++ b/tests/specs/unit/WorkerHealthAdapterSpec.cfc @@ -0,0 +1,150 @@ +component extends="testbox.system.BaseSpec" { + + function run() { + describe( "worker health snapshot adapter", function() { + it( "requires an explicit pool and never treats the metric name as a default", function() { + var adapter = new cbq.models.Telemetry.WorkerHealthAdapter(); + for ( var options in [ {}, { pool : "" }, { pool : [] } ] ) { + expect( function() { + adapter.sample( { name : "default", options : options } ); + } ).toThrow( "cbq.Telemetry.MissingWorkerPool" ); + } + expect( function() { + adapter.sample( { name : "default" } ); + } ).toThrow( "cbq.Telemetry.MissingWorkerPool" ); + } ); + it( "resolves the configured pool freshly for every snapshot without exposing options", function() { + var calls = 0; + var quantity = 2; + var adapter = prepareMock( new cbq.models.Telemetry.WorkerHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function( pool ) { + expect( pool ).toBe( "outbound" ); + calls++; + return { + getQuantity : function() { + return quantity; + } + }; + } + } + ); + var context = { + name : "mail", + options : { + pool : "outbound", + secret : "PRIVATE" + } + }; + expect( adapter.sample( context ).configuredWorkers ).toBe( 2 ); + quantity = 4; + expect( adapter.sample( context ).configuredWorkers ).toBe( 4 ); + expect( calls ).toBe( 2 ); + expect( serializeJSON( adapter.sample( context ) ) ).notToInclude( "PRIVATE" ); + } ); + it( "reports measured activity rather than executor capacity", function() { + var adapter = new cbq.models.Telemetry.WorkerHealthAdapter(); + var snapshot = adapter.samplePool( { + getQuantity : function() { + return 4; + }, + getCurrentExecutorCount : function() { + return 4; + }, + getExecutor : function() { + return { + getStats : function() { + return { + features : { taskMethods : true }, + activeCount : 1 + }; + } + }; + } + } ); + expect( snapshot.configuredWorkers ).toBe( 4 ); + expect( snapshot.activeExecutions ).toBe( 1 ); + expect( snapshot ).notToHaveKey( "activeWorkers" ); + expect( snapshot ).notToHaveKey( "lastHeartbeatAt" ); + } ); + it( "omits unsupported or unavailable activity instead of reporting zero", function() { + var adapter = new cbq.models.Telemetry.WorkerHealthAdapter(); + for ( + var stats in [ + {}, + { activeCount : 0 }, + { + features : { taskMethods : false }, + activeCount : 0 + } + ] + ) { + var snapshot = adapter.samplePool( { + getQuantity : function() { + return 4; + }, + getExecutor : function() { + return { + getStats : function() { + return stats; + } + }; + } + } ); + expect( snapshot ).toBe( { configuredWorkers : 4 } ); + } + expect( + adapter.samplePool( { + getQuantity : function() { + return 4; + } + } ) + ).toBe( { configuredWorkers : 4 } ); + } ); + it( "preserves missing pool errors rather than inventing a snapshot", function() { + var adapter = prepareMock( new cbq.models.Telemetry.WorkerHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function() { + throw( type = "cbq.MissingWorkerPool" ); + } + } + ); + expect( function() { + adapter.sample( { options : { pool : "missing" } } ); + } ).toThrow( "cbq.MissingWorkerPool" ); + } ); + it( "reads supported activity from an actual ColdBox executor", function() { + var native = createObject( "java", "java.util.concurrent.Executors" ).newFixedThreadPool( + javacast( "int", 1 ) + ); + try { + var executor = new coldbox.system.async.executors.Executor( "health-adapter", native ); + var adapter = new cbq.models.Telemetry.WorkerHealthAdapter(); + var snapshot = adapter.samplePool( { + getQuantity : function() { + return 1; + }, + getExecutor : function() { + return executor; + } + } ); + var stats = executor.getStats(); + if ( + stats.keyExists( "features" ) && stats.features.keyExists( "taskMethods" ) && stats.features.taskMethods + ) { + expect( snapshot.activeExecutions ).toBe( 0 ); + } else { + expect( snapshot ).notToHaveKey( "activeExecutions" ); + } + } finally { + native.shutdownNow(); + } + } ); + } ); + } + +} From 38142565da4e0bcc7cd4a8c5aac514d298e235f1 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 16:04:34 -0600 Subject: [PATCH 2/7] Restore the query factory after dialect compilation tests --- .../DBProviderTimeoutWatcherSpec.cfc | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc index c4b48af..834654e 100644 --- a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc +++ b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc @@ -154,14 +154,20 @@ component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" { return []; } ); + var originalNewQuery = variables.provider.newQuery; prepareMock( variables.provider ).$( "newQuery", builder ); - variables.provider.fetchPotentiallyOpenRecords( capacity = 10, pool = variables.pool ); - - var sql = builder.toSQL(); - expect( sql ).toInclude( "CASE WHEN #arguments.quotedColumn# = ? THEN 1 ELSE 2 END ASC" ); - expect( sql ).notToInclude( variables.pool.getUniqueId() ); - var bindings = builder.getBindings().map( ( binding ) => isStruct( binding ) ? binding.value : binding ); - expect( bindings ).toInclude( variables.pool.getUniqueId() ); + try { + variables.provider.fetchPotentiallyOpenRecords( capacity = 10, pool = variables.pool ); + + var sql = builder.toSQL(); + expect( sql ).toInclude( "CASE WHEN #arguments.quotedColumn# = ? THEN 1 ELSE 2 END ASC" ); + expect( sql ).notToInclude( variables.pool.getUniqueId() ); + var bindings = builder.getBindings().map( ( binding ) => isStruct( binding ) ? binding.value : binding ); + expect( bindings ).toInclude( variables.pool.getUniqueId() ); + } finally { + // Cleanup must use a fresh real builder, not this dialect-only ordered pretend query. + variables.provider.$( method = "newQuery", callback = originalNewQuery ); + } } private any function makeWorkerPool( required any provider ) { From 905498243396df5213ba4633e843803991d7f042 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 16:08:16 -0600 Subject: [PATCH 3/7] Restore a fresh WireBox query factory without rebinding its provider mixer --- .../Providers/DBProviderTimeoutWatcherSpec.cfc | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc index 834654e..c4b3372 100644 --- a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc +++ b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc @@ -154,7 +154,8 @@ component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" { return []; } ); - var originalNewQuery = variables.provider.newQuery; + var injector = getWireBox(); + var provider = variables.provider; prepareMock( variables.provider ).$( "newQuery", builder ); try { variables.provider.fetchPotentiallyOpenRecords( capacity = 10, pool = variables.pool ); @@ -166,7 +167,13 @@ component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" { expect( bindings ).toInclude( variables.pool.getUniqueId() ); } finally { // Cleanup must use a fresh real builder, not this dialect-only ordered pretend query. - variables.provider.$( method = "newQuery", callback = originalNewQuery ); + // WireBox's provider mixer depends on the called method name, so do not invoke it as a MockBox callback. + variables.provider.$( + method = "newQuery", + callback = function() { + return injector.getInstance( "QueryBuilder@qb", targetObject = provider ); + } + ); } } From 5a250f3a27f0e37ab82f3c12dfcaef525e2b49f6 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 16:08:31 -0600 Subject: [PATCH 4/7] Use named arguments consistently in the fixture query factory --- .../integration/Providers/DBProviderTimeoutWatcherSpec.cfc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc index c4b3372..bed3817 100644 --- a/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc +++ b/tests/specs/integration/Providers/DBProviderTimeoutWatcherSpec.cfc @@ -171,7 +171,7 @@ component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" { variables.provider.$( method = "newQuery", callback = function() { - return injector.getInstance( "QueryBuilder@qb", targetObject = provider ); + return injector.getInstance( name = "QueryBuilder@qb", targetObject = provider ); } ); } From 7e7fdd45f4a25437ce0c214b0c3c476b98987373 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 16:27:50 -0600 Subject: [PATCH 5/7] Combine queue and worker health in a provider-owned snapshot --- docs/worker-health-adapter.md | 35 +++--- models/Providers/DBProvider.cfc | 13 +++ models/Telemetry/DatabaseQueueSnapshot.cfc | 60 ++++++++++ models/Telemetry/QueueHealthAdapter.cfc | 66 +++++++++++ models/Telemetry/WorkerHealthAdapter.cfc | 38 +----- .../Providers/DBProviderQueueHealthSpec.cfc | 40 +++++++ tests/specs/unit/QueueHealthAdapterSpec.cfc | 109 ++++++++++++++++++ 7 files changed, 309 insertions(+), 52 deletions(-) create mode 100644 models/Telemetry/DatabaseQueueSnapshot.cfc create mode 100644 models/Telemetry/QueueHealthAdapter.cfc create mode 100644 tests/specs/integration/Providers/DBProviderQueueHealthSpec.cfc create mode 100644 tests/specs/unit/QueueHealthAdapterSpec.cfc diff --git a/docs/worker-health-adapter.md b/docs/worker-health-adapter.md index 94d0f2b..a9ec0d7 100644 --- a/docs/worker-health-adapter.md +++ b/docs/worker-health-adapter.md @@ -1,35 +1,38 @@ -# Worker health snapshot adapter +# Queue health snapshot adapter -`WorkerHealthAdapter@cbq` provides read-only snapshots of a registered cbq worker pool. It does not start workers, poll the queue provider, publish metrics or depend on Sentry. Each call resolves the pool again, so it follows the current registered pool rather than caching a stale instance. - -For Sentry automatic collection, select the adapter explicitly: +`QueueHealthAdapter@cbq` combines supported worker and queue measurements in one read-only snapshot. It does not start workers, reserve jobs, publish metrics or depend on Sentry. Each call resolves the current pool and its provider. ```cfml moduleSettings.sentry.automaticCollectors = { enabled: true, - queueWorkers: [ { - // Fixed metric label; this does not choose a pool. + queues: [ { + // Fixed logical metric label; independent of provider pool/queue identifiers. name: "mail", - // Provider-owned snapshot implementation; other queue providers use their own adapters. - adapter: "WorkerHealthAdapter@cbq", - // Explicit cbq pool selection. No default pool is assumed. + // Explicit provider-owned implementation. Other queue systems use their own adapters. + adapter: "QueueHealthAdapter@cbq", + // Required cbq pool. Its connection chooses the provider; its queue selection chooses the queues. options: { pool: "outbound" } } ] }; ``` -Sentry also needs its existing valid DSN and `enableMetrics:true` settings. No Sentry setting or dependency is needed to use the snapshot directly: +Sentry also needs its existing valid DSN and `enableMetrics:true`. Its `queues` collector handles worker activity and backlog together; separate worker/database collector definitions are not needed. All measurements use the configured logical queue label. `options.queue` can override the selected queue(s); otherwise the pool's string/array/wildcard queue selection applies. + +The adapter follows `sample(context)` structurally without importing Sentry's interface. It can be used directly without Sentry: ```cfml -snapshot = wirebox.getInstance( "WorkerHealthAdapter@cbq" ) +snapshot = wirebox.getInstance( "QueueHealthAdapter@cbq" ) .sample( { options: { pool: "outbound" } } ); -// Or samplePool(workerPool) when the caller already has the pool instance. ``` -The adapter follows the optional `ISnapshotAdapter.sample(context)` contract structurally; it does not import Sentry's interface. `options.pool` must be supplied explicitly. Missing configuration or an unregistered pool throws an error so the caller can record a failed sample rather than a false zero. +It returns `configuredWorkers` and supported `activeExecutions`. If the pool's provider exposes `getQueueHealth(queue)`, it also includes supported `depth`, `oldestAgeSeconds`, `runnable`, `delayed`, `reserved`, `staleReservations`, `retries` and `exhausted` fields. Providers own their snapshot logic; cbq's database provider uses its configured table, query options and datasource. Database counts exclude completed/failed jobs; unclaimed work is runnable or delayed, claimed work is reserved, and expired claims are stale. Queue selections are bound query parameters; `*` selects all queues. No database configuration or cbq schema knowledge is required in Sentry. + +Missing capabilities stay absent. An unstarted executor does not imply zero activity; supported idle executors can report zero. Queue/database sampling errors propagate to the caller's failure diagnostics, rather than pretending a backlog is zero. There are no fabricated worker heartbeats, job IDs, payloads or raw exceptions in successful snapshots. + +`WorkerHealthAdapter@cbq` remains an alias, and `samplePool(workerPool)` remains available for earlier manual worker integrations. The adapter must be present in the installed cbq release before selecting its mapping in Sentry. Neither package acquires a dependency on the other. -Snapshots contain `configuredWorkers` from pool quantity and `activeExecutions` only when the executor advertises `features.taskMethods` and reports `activeCount`. Configured concurrency and current executor capacity are not active worker counts. ColdBox versions or executor types without supported activity statistics omit `activeExecutions`; an unstarted executor also leaves it absent. A measured idle executor can report zero. The snapshot does not manufacture a worker heartbeat, retry totals, queue backlog, job identifiers or payload data. +Earlier local verification of the worker-only implementation and the companion Sentry suite is recorded in the PR. The unified queue changes add combined/backlog-only snapshots, provider-owned table/datasource selection, multiple queues and wildcard/parameter binding coverage. Current local and hosted results are recorded on the draft PRs. -Local verification and release requirements are recorded with the companion Sentry change. This adapter must be present in the installed cbq version before configuring its mapping in Sentry; it is not included in older cbq releases. +Worker measurements always describe the entire pool, even when `options.queue` narrows the backlog selection. Prefer one combined collector per pool; use backlog-only snapshots for extra per-queue breakdowns so shared pool activity is not counted repeatedly. -Local checks passed on prepared Lucee 5.4.8.2, BoxLang 1.18.0+66 and Adobe 2023 update 25 runtimes (Java 21): 6/6 adapter specs and 134/134 companion Sentry specs per engine, with zero failures/errors/skips. The latter includes ten PostgreSQL 18.1 cases with actual cbq workers, including automatic WireBox resolution of this adapter and idle/busy worker activity. cbq source was `next` base `fad884a` plus this adapter; qb 14.1.0, ColdBox 7.5.2 and TestBox 3.2 were supplied by the isolated Sentry harness. The complete cbq suite was not run locally. This does not qualify crash recovery, actual worker heartbeats, other queue providers or real Sentry delivery/indexing. +The unified implementation passed 9/9 adapter specs and 137/137 companion Sentry specs on each prepared Lucee 5, BoxLang and Adobe 2023 runtime, including eleven real PostgreSQL/cbq cases. New MySQL integration specs exercise provider queue snapshots in cbq's hosted suite. Current hosted results and release prerequisites are recorded on the draft PRs. Formatting and whitespace checks pass; installed application modules were not modified. diff --git a/models/Providers/DBProvider.cfc b/models/Providers/DBProvider.cfc index 0df5e2e..0aeb304 100644 --- a/models/Providers/DBProvider.cfc +++ b/models/Providers/DBProvider.cfc @@ -697,6 +697,19 @@ component accessors="true" extends="AbstractQueueProvider" { return records; } + /** Read the configured database queue without reserving jobs or starting workers. */ + public struct function getQueueHealth( required any queue ) { + var queryFactory = function() { + return newQuery(); + }; + var snapshotAdapter = new cbq.models.Telemetry.DatabaseQueueSnapshot( + queryFactory = queryFactory, + table = variables.tableName, + queryOptions = variables.defaultQueryOptions + ); + return snapshotAdapter.snapshot( arguments.queue ); + } + public QueryBuilder function newQuery() provider="QueryBuilder@qb" { } diff --git a/models/Telemetry/DatabaseQueueSnapshot.cfc b/models/Telemetry/DatabaseQueueSnapshot.cfc new file mode 100644 index 0000000..fa10980 --- /dev/null +++ b/models/Telemetry/DatabaseQueueSnapshot.cfc @@ -0,0 +1,60 @@ +/** Read-only cbq database queue snapshot using the provider's availability and lease fields. */ +component { + + function init( + required function queryFactory, + string table = "cbq_jobs", + struct queryOptions = {} + ) { + variables.queryFactory = arguments.queryFactory; + variables.table = arguments.table; + variables.queryOptions = duplicate( arguments.queryOptions ); + return this; + } + function snapshot( required any queue ) { + var builder = variables.queryFactory(); + var grammar = builder.getGrammar(); + var available = grammar.wrapValue( "availableDate" ); + var reserved = grammar.wrapValue( "reservedDate" ); + var owner = grammar.wrapValue( "reservedBy" ); + var created = grammar.wrapValue( "createdDate" ); + var unclaimed = reserved & " IS NULL AND " & owner & " IS NULL"; + var claimed = "(" & reserved & " IS NOT NULL OR " & owner & " IS NOT NULL)"; + var now = int( createObject( "java", "java.lang.System" ).currentTimeMillis() / 1000 ); + var queues = isArray( arguments.queue ) ? arguments.queue : [ arguments.queue ]; + if ( !queues.len() ) throw( type = "cbq.Telemetry.InvalidQueueSelection" ); + for ( var queueName in queues ) { + if ( isNull( queueName ) || !isSimpleValue( queueName ) ) + throw( type = "cbq.Telemetry.InvalidQueueSelection" ); + } + builder.from( variables.table ); + if ( !arrayFind( queues, "*" ) ) builder.whereIn( "queue", queues ); + var rows = builder + .whereNull( "completedDate" ) + .whereNull( "failedDate" ) + .selectRaw( + "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS runnable", + [ now ] + ) + .selectRaw( + "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " > ? THEN 1 ELSE 0 END),0) AS delayed", + [ now ] + ) + .selectRaw( "COALESCE(SUM(CASE WHEN " & claimed & " THEN 1 ELSE 0 END),0) AS reserved" ) + .selectRaw( + "COALESCE(SUM(CASE WHEN " & claimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS staleReservations", + [ now ] + ) + .selectRaw( "MIN(CASE WHEN " & unclaimed & " THEN " & created & " ELSE NULL END) AS oldestCreatedAt" ) + .get( options = variables.queryOptions ); + if ( !isArray( rows ) || rows.len() != 1 ) throw( type = "cbq.Telemetry.InvalidQueueHealthResult" ); + var snapshot = rows[ 1 ]; + snapshot[ "depth" ] = snapshot.runnable + snapshot.delayed; + snapshot[ "oldestAgeSeconds" ] = snapshot.depth > 0 && snapshot.keyExists( "oldestCreatedAt" ) && !isNull( + snapshot.oldestCreatedAt + ) && isNumeric( snapshot.oldestCreatedAt ) ? max( 0, now - snapshot.oldestCreatedAt ) : 0; + snapshot.delete( "oldestCreatedAt" ); + return snapshot; + } + +} diff --git a/models/Telemetry/QueueHealthAdapter.cfc b/models/Telemetry/QueueHealthAdapter.cfc new file mode 100644 index 0000000..50ab540 --- /dev/null +++ b/models/Telemetry/QueueHealthAdapter.cfc @@ -0,0 +1,66 @@ +/** Provider-owned queue snapshots. Uses sample(context) without requiring Sentry. */ +component { + + property name="config" inject="Config@cbq"; + + struct function sample( required struct context ) { + if ( + !arguments.context.keyExists( "options" ) || !isStruct( arguments.context.options ) || + !arguments.context.options.keyExists( "pool" ) || isNull( arguments.context.options.pool ) || !isSimpleValue( + arguments.context.options.pool + ) || + !len( trim( arguments.context.options.pool ) ) + ) { + throw( + type = "cbq.Telemetry.MissingWorkerPool", + message = "Configure options.pool explicitly for the worker health adapter." + ); + } + var pool = variables.config.getWorkerPool( arguments.context.options.pool ); + var snapshot = samplePool( pool ); + if ( !structKeyExists( pool, "getConnection" ) ) return snapshot; + var provider = pool.getConnection().getProvider(); + if ( !structKeyExists( provider, "getQueueHealth" ) ) return snapshot; + var queueSelection = arguments.context.options.keyExists( "queue" ) ? arguments.context.options.queue : pool.getQueue(); + var observed = provider.getQueueHealth( queueSelection ); + if ( !isStruct( observed ) ) throw( type = "cbq.Telemetry.InvalidQueueHealthResult" ); + for ( + var field in [ + "depth", + "oldestAgeSeconds", + "runnable", + "delayed", + "reserved", + "staleReservations", + "retries", + "exhausted" + ] + ) { + if ( + observed.keyExists( field ) && !isNull( observed[ field ] ) && isNumeric( observed[ field ] ) && observed[ + field + ] >= 0 && observed[ field ] <= 1.7976931348623157E308 + ) + snapshot[ field ] = observed[ field ]; + } + return snapshot; + } + + struct function samplePool( required any pool ) { + var snapshot = { "configuredWorkers" : arguments.pool.getQuantity() }; + try { + var stats = arguments.pool.getExecutor().getStats(); + // Some executors return a fallback zero when activity cannot be measured. + if ( + stats.keyExists( "features" ) && stats.features.keyExists( "taskMethods" ) && stats.features.taskMethods && + stats.keyExists( "activeCount" ) + ) { + snapshot[ "activeExecutions" ] = stats.activeCount; + } + } catch ( any unavailable ) { + // An unstarted/unsupported executor does not imply zero activity or a worker heartbeat. + } + return snapshot; + } + +} diff --git a/models/Telemetry/WorkerHealthAdapter.cfc b/models/Telemetry/WorkerHealthAdapter.cfc index 2bf6254..c684b83 100644 --- a/models/Telemetry/WorkerHealthAdapter.cfc +++ b/models/Telemetry/WorkerHealthAdapter.cfc @@ -1,39 +1,5 @@ -/** Read-only worker snapshots. Compatible with Sentry's sample(context) contract; Sentry is not required. */ -component { +/** Compatibility alias for integrations using the earlier worker-only adapter name. */ +component extends="cbq.models.Telemetry.QueueHealthAdapter" { - property name="config" inject="Config@cbq"; - - struct function sample( required struct context ) { - if ( - !arguments.context.keyExists( "options" ) || !isStruct( arguments.context.options ) || - !arguments.context.options.keyExists( "pool" ) || isNull( arguments.context.options.pool ) || !isSimpleValue( - arguments.context.options.pool - ) || - !len( trim( arguments.context.options.pool ) ) - ) { - throw( - type = "cbq.Telemetry.MissingWorkerPool", - message = "Configure options.pool explicitly for the worker health adapter." - ); - } - return samplePool( variables.config.getWorkerPool( arguments.context.options.pool ) ); - } - - struct function samplePool( required any pool ) { - var snapshot = { "configuredWorkers" : arguments.pool.getQuantity() }; - try { - var stats = arguments.pool.getExecutor().getStats(); - // Some executors return a fallback zero when activity cannot be measured. - if ( - stats.keyExists( "features" ) && stats.features.keyExists( "taskMethods" ) && stats.features.taskMethods && - stats.keyExists( "activeCount" ) - ) { - snapshot[ "activeExecutions" ] = stats.activeCount; - } - } catch ( any unavailable ) { - // An unstarted/unsupported executor does not imply zero activity or a worker heartbeat. - } - return snapshot; - } } diff --git a/tests/specs/integration/Providers/DBProviderQueueHealthSpec.cfc b/tests/specs/integration/Providers/DBProviderQueueHealthSpec.cfc new file mode 100644 index 0000000..1966a46 --- /dev/null +++ b/tests/specs/integration/Providers/DBProviderQueueHealthSpec.cfc @@ -0,0 +1,40 @@ +component extends="tests.resources.ModuleIntegrationSpec" appMapping="/app" { + + function run() { + describe( "database provider queue health", function() { + beforeEach( function() { + variables.provider = getWireBox() + .getInstance( "DBProvider@cbq" ) + .setProperties( { datasource : "cbq" } ); + variables.provider + .newQuery() + .from( "cbq_jobs" ) + .delete(); + } ); + afterEach( function() { + variables.provider + .newQuery() + .from( "cbq_jobs" ) + .delete(); + } ); + it( "returns measured zeros for an empty queue", function() { + var snapshot = variables.provider.getQueueHealth( "mail" ); + expect( snapshot.depth ).toBe( 0 ); + expect( snapshot.runnable ).toBe( 0 ); + expect( snapshot.reserved ).toBe( 0 ); + expect( snapshot.oldestAgeSeconds ).toBe( 0 ); + } ); + it( "reads selected queues without reserving jobs or mixing in other queues", function() { + variables.provider.push( "mail", getWireBox().getInstance( "SendWelcomeEmailJob" ) ); + variables.provider.push( "pdf", getWireBox().getInstance( "SendWelcomeEmailJob" ) ); + variables.provider.push( "mail' OR 1=1 --", getWireBox().getInstance( "SendWelcomeEmailJob" ) ); + expect( variables.provider.getQueueHealth( [ "mail", "pdf" ] ).depth ).toBe( 2 ); + expect( variables.provider.getQueueHealth( "*" ).depth ).toBe( 3 ); + expect( variables.provider.getQueueHealth( [ "*" ] ).depth ).toBe( 3 ); + expect( variables.provider.getQueueHealth( "mail' OR 1=1 --" ).depth ).toBe( 1 ); + expect( variables.provider.getQueueHealth( "*" ).reserved ).toBe( 0 ); + } ); + } ); + } + +} diff --git a/tests/specs/unit/QueueHealthAdapterSpec.cfc b/tests/specs/unit/QueueHealthAdapterSpec.cfc new file mode 100644 index 0000000..df2417f --- /dev/null +++ b/tests/specs/unit/QueueHealthAdapterSpec.cfc @@ -0,0 +1,109 @@ +component extends="testbox.system.BaseSpec" { + + function run() { + describe( "provider-owned queue health", function() { + it( "combines worker activity with the provider's selected queue snapshot", function() { + var selections = []; + var provider = { + getQueueHealth : function( queue ) { + selections.append( queue ); + return { + depth : 4, + oldestAgeSeconds : 10, + runnable : 3, + delayed : 1, + privatePayload : "PRIVATE" + }; + } + }; + var pool = { + getQuantity : function() { + return 2; + }, + getQueue : function() { + return [ "mail", "pdf" ]; + }, + getConnection : function() { + return { + getProvider : function() { + return provider; + } + }; + } + }; + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function() { + return pool; + } + } + ); + var snapshot = adapter.sample( { options : { pool : "outbound" } } ); + expect( snapshot.configuredWorkers ).toBe( 2 ); + expect( snapshot.depth ).toBe( 4 ); + expect( selections[ 1 ] ).toBe( [ "mail", "pdf" ] ); + expect( serializeJSON( snapshot ) ).notToInclude( "PRIVATE" ); + adapter.sample( { options : { pool : "outbound", queue : "mail" } } ); + expect( selections[ 2 ] ).toBe( "mail" ); + } ); + it( "omits backlog when a provider does not support a queue snapshot", function() { + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function() { + return { + getQuantity : function() { + return 3; + }, + getConnection : function() { + return { + getProvider : function() { + return {}; + } + }; + } + }; + } + } + ); + expect( adapter.sample( { options : { pool : "outbound" } } ) ).toBe( { configuredWorkers : 3 } ); + } ); + it( "propagates failed provider snapshots rather than pretending backlog is zero", function() { + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function() { + return { + getQuantity : function() { + return 3; + }, + getQueue : function() { + return "mail"; + }, + getConnection : function() { + return { + getProvider : function() { + return { + getQueueHealth : function() { + throw( type = "SnapshotFailed" ); + } + }; + } + }; + } + }; + } + } + ); + expect( function() { + adapter.sample( { options : { pool : "outbound" } } ); + } ).toThrow( "SnapshotFailed" ); + } ); + } ); + } + +} From cf4a26fe1edab1866d9beb4448b222011900404a Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sat, 24 Oct 2026 16:34:56 -0600 Subject: [PATCH 6/7] Quote queue snapshot aliases for supported database grammars --- models/Telemetry/DatabaseQueueSnapshot.cfc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/models/Telemetry/DatabaseQueueSnapshot.cfc b/models/Telemetry/DatabaseQueueSnapshot.cfc index fa10980..9d6cae6 100644 --- a/models/Telemetry/DatabaseQueueSnapshot.cfc +++ b/models/Telemetry/DatabaseQueueSnapshot.cfc @@ -33,19 +33,19 @@ component { .whereNull( "completedDate" ) .whereNull( "failedDate" ) .selectRaw( - "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS runnable", + "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS " & grammar.wrapValue( "runnable" ), [ now ] ) .selectRaw( - "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " > ? THEN 1 ELSE 0 END),0) AS delayed", + "COALESCE(SUM(CASE WHEN " & unclaimed & " AND " & available & " > ? THEN 1 ELSE 0 END),0) AS " & grammar.wrapValue( "delayed" ), [ now ] ) - .selectRaw( "COALESCE(SUM(CASE WHEN " & claimed & " THEN 1 ELSE 0 END),0) AS reserved" ) + .selectRaw( "COALESCE(SUM(CASE WHEN " & claimed & " THEN 1 ELSE 0 END),0) AS " & grammar.wrapValue( "reserved" ) ) .selectRaw( - "COALESCE(SUM(CASE WHEN " & claimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS staleReservations", + "COALESCE(SUM(CASE WHEN " & claimed & " AND " & available & " <= ? THEN 1 ELSE 0 END),0) AS " & grammar.wrapValue( "staleReservations" ), [ now ] ) - .selectRaw( "MIN(CASE WHEN " & unclaimed & " THEN " & created & " ELSE NULL END) AS oldestCreatedAt" ) + .selectRaw( "MIN(CASE WHEN " & unclaimed & " THEN " & created & " ELSE NULL END) AS " & grammar.wrapValue( "oldestCreatedAt" ) ) .get( options = variables.queryOptions ); if ( !isArray( rows ) || rows.len() != 1 ) throw( type = "cbq.Telemetry.InvalidQueueHealthResult" ); var snapshot = rows[ 1 ]; From ad951647c29428a6a1287fffd08bcf38b6f840f4 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Sun, 25 Oct 2026 11:15:40 -0600 Subject: [PATCH 7/7] Distinguish queue connections from worker pools in health snapshots --- docs/worker-health-adapter.md | 46 ++++-- models/Telemetry/QueueHealthAdapter.cfc | 47 ++++-- tests/specs/unit/QueueHealthAdapterSpec.cfc | 152 ++++++++++++++++++- tests/specs/unit/WorkerHealthAdapterSpec.cfc | 18 ++- 4 files changed, 229 insertions(+), 34 deletions(-) diff --git a/docs/worker-health-adapter.md b/docs/worker-health-adapter.md index a9ec0d7..0459ffb 100644 --- a/docs/worker-health-adapter.md +++ b/docs/worker-health-adapter.md @@ -1,38 +1,64 @@ # Queue health snapshot adapter -`QueueHealthAdapter@cbq` combines supported worker and queue measurements in one read-only snapshot. It does not start workers, reserve jobs, publish metrics or depend on Sentry. Each call resolves the current pool and its provider. +`QueueHealthAdapter@cbq` reads queue backlog through an explicit connection, or combines worker and queue measurements through an explicit worker pool. It does not start workers, reserve jobs, publish metrics or depend on Sentry. Each call resolves the current connection or worker pool and its provider. ```cfml moduleSettings.sentry.automaticCollectors = { + // Start Sentry's periodic sampler. enabled: true, + // One provider-neutral list for queue and worker measurements. queues: [ { - // Fixed logical metric label; independent of provider pool/queue identifiers. + // Fixed logical metric label; independent of cbq worker-pool and queue identifiers. name: "mail", // Explicit provider-owned implementation. Other queue systems use their own adapters. adapter: "QueueHealthAdapter@cbq", - // Required cbq pool. Its connection chooses the provider; its queue selection chooses the queues. - options: { pool: "outbound" } + // Select worker activity plus backlog from this cbq worker pool. + options: { + // Its connection chooses the provider; its queue selection chooses the queues. + workerPool: "outbound" + } } ] }; ``` -Sentry also needs its existing valid DSN and `enableMetrics:true`. Its `queues` collector handles worker activity and backlog together; separate worker/database collector definitions are not needed. All measurements use the configured logical queue label. `options.queue` can override the selected queue(s); otherwise the pool's string/array/wildcard queue selection applies. +Sentry also needs its existing valid DSN and `enableMetrics:true`. Its `queues` collector handles worker activity and backlog together; separate worker/database collector definitions are not needed. All measurements use the configured logical queue label. `options.queue` can override the selected queue(s); otherwise the worker pool's string/array/wildcard queue selection applies. + +For backlog without local workers, select a connection instead: + +```cfml +// Choose queue backlog without collecting shared worker activity. +moduleSettings.sentry.automaticCollectors.queues = [ { + // Fixed logical metric label. + name: "mail", + // Provider-owned adapter; no worker pool is required. + adapter: "QueueHealthAdapter@cbq", + // Explicit source and optional queue selection. + options: { + // Registered cbq connection; its provider owns storage and database configuration. + connection: "database", + // Optional queue name, array or wildcard. Omit to use the connection's default queue. + queue: "mail" + } +} ]; +``` + +Configure exactly one of `options.workerPool` or `options.connection`. Missing, empty, nonsimple, ambiguous or legacy `options.pool` selection raises `cbq.Telemetry.InvalidQueueHealthSelection`; no source is inferred from a metric label. Missing registered connections/worker pools and provider sampling failures retain their original errors. The adapter follows `sample(context)` structurally without importing Sentry's interface. It can be used directly without Sentry: ```cfml snapshot = wirebox.getInstance( "QueueHealthAdapter@cbq" ) - .sample( { options: { pool: "outbound" } } ); + .sample( { options: { workerPool: "outbound" } } ); ``` -It returns `configuredWorkers` and supported `activeExecutions`. If the pool's provider exposes `getQueueHealth(queue)`, it also includes supported `depth`, `oldestAgeSeconds`, `runnable`, `delayed`, `reserved`, `staleReservations`, `retries` and `exhausted` fields. Providers own their snapshot logic; cbq's database provider uses its configured table, query options and datasource. Database counts exclude completed/failed jobs; unclaimed work is runnable or delayed, claimed work is reserved, and expired claims are stale. Queue selections are bound query parameters; `*` selects all queues. No database configuration or cbq schema knowledge is required in Sentry. +Worker-pool selection returns `configuredWorkers` and supported `activeExecutions`. If the connection's provider exposes `getQueueHealth(queue)`, either selection includes supported `depth`, `oldestAgeSeconds`, `runnable`, `delayed`, `reserved`, `staleReservations`, `retries` and `exhausted` fields. Connection-only snapshots contain no worker fields. Providers own their snapshot logic; cbq's database provider uses its configured table, query options and datasource. Database counts exclude completed/failed jobs; unclaimed work is runnable or delayed, claimed work is reserved, and expired claims are stale. Queue selections are bound query parameters; `*` selects all queues. No database configuration or cbq schema knowledge is required in Sentry. -Missing capabilities stay absent. An unstarted executor does not imply zero activity; supported idle executors can report zero. Queue/database sampling errors propagate to the caller's failure diagnostics, rather than pretending a backlog is zero. There are no fabricated worker heartbeats, job IDs, payloads or raw exceptions in successful snapshots. +Missing capabilities stay absent. A connection-only provider without queue health support returns an empty snapshot, not zero backlog or worker activity. An unstarted executor does not imply zero activity; supported idle executors can report zero. Queue/database sampling errors propagate to the caller's failure diagnostics, rather than pretending a backlog is zero. There are no fabricated worker heartbeats, job IDs, payloads or raw exceptions in successful snapshots. `WorkerHealthAdapter@cbq` remains an alias, and `samplePool(workerPool)` remains available for earlier manual worker integrations. The adapter must be present in the installed cbq release before selecting its mapping in Sentry. Neither package acquires a dependency on the other. Earlier local verification of the worker-only implementation and the companion Sentry suite is recorded in the PR. The unified queue changes add combined/backlog-only snapshots, provider-owned table/datasource selection, multiple queues and wildcard/parameter binding coverage. Current local and hosted results are recorded on the draft PRs. -Worker measurements always describe the entire pool, even when `options.queue` narrows the backlog selection. Prefer one combined collector per pool; use backlog-only snapshots for extra per-queue breakdowns so shared pool activity is not counted repeatedly. +Worker measurements always describe the entire worker pool, even when `options.queue` narrows the backlog selection. Prefer one combined collector per worker pool; use connection-only snapshots for extra per-queue breakdowns so shared worker activity is not counted repeatedly. -The unified implementation passed 9/9 adapter specs and 137/137 companion Sentry specs on each prepared Lucee 5, BoxLang and Adobe 2023 runtime, including eleven real PostgreSQL/cbq cases. New MySQL integration specs exercise provider queue snapshots in cbq's hosted suite. Current hosted results and release prerequisites are recorded on the draft PRs. Formatting and whitespace checks pass; installed application modules were not modified. +Before the explicit connection/worker-pool selector correction, the unified implementation passed 9/9 adapter specs and 137/137 companion Sentry specs on each prepared Lucee 5, BoxLang and Adobe 2023 runtime, including eleven real PostgreSQL/cbq cases. MySQL integration specs exercise provider queue snapshots in cbq's hosted suite. Current selector coverage, hosted results and release prerequisites are recorded on the draft PRs. Formatting and whitespace checks pass; installed application modules were not modified. diff --git a/models/Telemetry/QueueHealthAdapter.cfc b/models/Telemetry/QueueHealthAdapter.cfc index 50ab540..048c7d9 100644 --- a/models/Telemetry/QueueHealthAdapter.cfc +++ b/models/Telemetry/QueueHealthAdapter.cfc @@ -4,24 +4,43 @@ component { property name="config" inject="Config@cbq"; struct function sample( required struct context ) { - if ( - !arguments.context.keyExists( "options" ) || !isStruct( arguments.context.options ) || - !arguments.context.options.keyExists( "pool" ) || isNull( arguments.context.options.pool ) || !isSimpleValue( - arguments.context.options.pool - ) || - !len( trim( arguments.context.options.pool ) ) - ) { + if ( !arguments.context.keyExists( "options" ) || !isStruct( arguments.context.options ) ) { + throw( + type = "cbq.Telemetry.InvalidQueueHealthSelection", + message = "Configure exactly one of options.workerPool or options.connection." + ); + } + var options = arguments.context.options; + var hasWorkerPool = options.keyExists( "workerPool" ); + var hasConnection = options.keyExists( "connection" ); + if ( options.keyExists( "pool" ) || hasWorkerPool == hasConnection ) { throw( - type = "cbq.Telemetry.MissingWorkerPool", - message = "Configure options.pool explicitly for the worker health adapter." + type = "cbq.Telemetry.InvalidQueueHealthSelection", + message = "Configure exactly one of options.workerPool or options.connection; options.pool is not supported." ); } - var pool = variables.config.getWorkerPool( arguments.context.options.pool ); - var snapshot = samplePool( pool ); - if ( !structKeyExists( pool, "getConnection" ) ) return snapshot; - var provider = pool.getConnection().getProvider(); + var source = hasWorkerPool ? options.workerPool : options.connection; + if ( isNull( source ) || !isSimpleValue( source ) || !len( trim( source ) ) ) { + throw( + type = "cbq.Telemetry.InvalidQueueHealthSelection", + message = "The workerPool or connection selector must be a nonempty name." + ); + } + var snapshot = {}; + var connection = {}; + if ( hasWorkerPool ) { + var pool = variables.config.getWorkerPool( source ); + snapshot = samplePool( pool ); + if ( !structKeyExists( pool, "getConnection" ) ) return snapshot; + connection = pool.getConnection(); + } else { + connection = variables.config.getConnection( source ); + } + var provider = connection.getProvider(); if ( !structKeyExists( provider, "getQueueHealth" ) ) return snapshot; - var queueSelection = arguments.context.options.keyExists( "queue" ) ? arguments.context.options.queue : pool.getQueue(); + var queueSelection = options.keyExists( "queue" ) ? options.queue : ( + hasWorkerPool ? pool.getQueue() : connection.getDefaultQueue() + ); var observed = provider.getQueueHealth( queueSelection ); if ( !isStruct( observed ) ) throw( type = "cbq.Telemetry.InvalidQueueHealthResult" ); for ( diff --git a/tests/specs/unit/QueueHealthAdapterSpec.cfc b/tests/specs/unit/QueueHealthAdapterSpec.cfc index df2417f..d4e0b59 100644 --- a/tests/specs/unit/QueueHealthAdapterSpec.cfc +++ b/tests/specs/unit/QueueHealthAdapterSpec.cfc @@ -40,12 +40,17 @@ component extends="testbox.system.BaseSpec" { } } ); - var snapshot = adapter.sample( { options : { pool : "outbound" } } ); + var snapshot = adapter.sample( { options : { workerPool : "outbound" } } ); expect( snapshot.configuredWorkers ).toBe( 2 ); expect( snapshot.depth ).toBe( 4 ); expect( selections[ 1 ] ).toBe( [ "mail", "pdf" ] ); expect( serializeJSON( snapshot ) ).notToInclude( "PRIVATE" ); - adapter.sample( { options : { pool : "outbound", queue : "mail" } } ); + adapter.sample( { + options : { + workerPool : "outbound", + queue : "mail" + } + } ); expect( selections[ 2 ] ).toBe( "mail" ); } ); it( "omits backlog when a provider does not support a queue snapshot", function() { @@ -69,7 +74,7 @@ component extends="testbox.system.BaseSpec" { } } ); - expect( adapter.sample( { options : { pool : "outbound" } } ) ).toBe( { configuredWorkers : 3 } ); + expect( adapter.sample( { options : { workerPool : "outbound" } } ) ).toBe( { configuredWorkers : 3 } ); } ); it( "propagates failed provider snapshots rather than pretending backlog is zero", function() { var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( @@ -100,9 +105,148 @@ component extends="testbox.system.BaseSpec" { } ); expect( function() { - adapter.sample( { options : { pool : "outbound" } } ); + adapter.sample( { options : { workerPool : "outbound" } } ); } ).toThrow( "SnapshotFailed" ); } ); + it( "samples a connection without resolving workers and preserves queue selections", function() { + var selections = []; + var connections = 0; + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getWorkerPool : function() { + throw( type = "UnexpectedWorkerPoolResolution" ); + }, + getConnection : function( name ) { + expect( name ).toBe( "database" ); + connections++; + return { + getDefaultQueue : function() { + return "default-mail"; + }, + getProvider : function() { + return { + getQueueHealth : function( queue ) { + selections.append( queue ); + return { + depth : connections, + privatePayload : "PRIVATE", + configuredWorkers : 99 + }; + } + }; + } + }; + } + } + ); + expect( adapter.sample( { options : { connection : "database" } } ) ).toBe( { depth : 1 } ); + expect( selections[ 1 ] ).toBe( "default-mail" ); + for ( var queue in [ "mail", [ "mail", "pdf" ], "*" ] ) { + var sample = adapter.sample( { + options : { + connection : "database", + queue : queue + } + } ); + expect( sample ).toBe( { depth : selections.len() } ); + expect( selections[ selections.len() ] ).toBe( queue ); + } + expect( connections ).toBe( 4 ); + } ); + it( "rejects ambiguous, legacy and invalid source selectors", function() { + var adapter = new cbq.models.Telemetry.QueueHealthAdapter(); + for ( + var options in [ + {}, + { pool : "outbound" }, + { connection : "" }, + { connection : [] }, + { workerPool : " " }, + { workerPool : [] }, + { + workerPool : "outbound", + connection : "database" + }, + { + pool : "old", + workerPool : "outbound" + }, + { + pool : "old", + connection : "database" + } + ] + ) { + expect( function() { + adapter.sample( { name : "default", options : options } ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthSelection" ); + } + expect( function() { + adapter.sample( {} ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthSelection" ); + expect( function() { + adapter.sample( { options : [] } ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthSelection" ); + } ); + it( "omits unsupported connection-only backlog without inventing worker counts", function() { + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getConnection : function() { + return { + getProvider : function() { + return {}; + } + }; + } + } + ); + expect( adapter.sample( { options : { connection : "custom" } } ) ).toBe( {} ); + } ); + it( "preserves missing connection errors", function() { + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getConnection : function() { + throw( type = "cbq.MissingQueueConnection" ); + } + } + ); + expect( function() { + adapter.sample( { options : { connection : "missing" } } ); + } ).toThrow( "cbq.MissingQueueConnection" ); + } ); + it( "rejects invalid connection provider snapshots", function() { + var adapter = prepareMock( new cbq.models.Telemetry.QueueHealthAdapter() ).$property( + "config", + "variables", + { + getConnection : function() { + return { + getProvider : function() { + return { + getQueueHealth : function() { + return "unavailable"; + } + }; + } + }; + } + } + ); + expect( function() { + adapter.sample( { + options : { + connection : "database", + queue : "mail" + } + } ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthResult" ); + } ); } ); } diff --git a/tests/specs/unit/WorkerHealthAdapterSpec.cfc b/tests/specs/unit/WorkerHealthAdapterSpec.cfc index 0cfe1f3..9c0ea60 100644 --- a/tests/specs/unit/WorkerHealthAdapterSpec.cfc +++ b/tests/specs/unit/WorkerHealthAdapterSpec.cfc @@ -2,16 +2,22 @@ component extends="testbox.system.BaseSpec" { function run() { describe( "worker health snapshot adapter", function() { - it( "requires an explicit pool and never treats the metric name as a default", function() { + it( "requires an explicit worker pool and never treats the metric name as a default", function() { var adapter = new cbq.models.Telemetry.WorkerHealthAdapter(); - for ( var options in [ {}, { pool : "" }, { pool : [] } ] ) { + for ( + var options in [ + {}, + { workerPool : "" }, + { workerPool : [] } + ] + ) { expect( function() { adapter.sample( { name : "default", options : options } ); - } ).toThrow( "cbq.Telemetry.MissingWorkerPool" ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthSelection" ); } expect( function() { adapter.sample( { name : "default" } ); - } ).toThrow( "cbq.Telemetry.MissingWorkerPool" ); + } ).toThrow( "cbq.Telemetry.InvalidQueueHealthSelection" ); } ); it( "resolves the configured pool freshly for every snapshot without exposing options", function() { var calls = 0; @@ -34,7 +40,7 @@ component extends="testbox.system.BaseSpec" { var context = { name : "mail", options : { - pool : "outbound", + workerPool : "outbound", secret : "PRIVATE" } }; @@ -114,7 +120,7 @@ component extends="testbox.system.BaseSpec" { } ); expect( function() { - adapter.sample( { options : { pool : "missing" } } ); + adapter.sample( { options : { workerPool : "missing" } } ); } ).toThrow( "cbq.MissingWorkerPool" ); } ); it( "reads supported activity from an actual ColdBox executor", function() {