@pikku/queue-bullmq 0.12.8 → 0.12.9

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.12.9
+
+### Patch Changes
+
+- de9af6a: RPCs for Pikku Studio's migrated screens. Runtime state that must be visible on a deployed app lives in `@pikku/addon-admin`; local-copy tools stay in `@pikku/addon-console`.
+
+  `@pikku/addon-admin`:
+
+  - `admin:getSchedulerHistory` returns each scheduled task's last run, next run and recent runs, from a new `SchedulerService.getTaskRuns()` (empty by default). `InMemorySchedulerService` records the last 50 runs per cron task with status, duration and error. Scope `admin:schedules:read`.
+  - `admin:getQueueHistory({ queueNames?, limit? })` returns live counts and recent jobs per queue, from a new optional `QueueService.inspect(queueName, { limit })`, implemented by `InMemoryQueueService` and `BullQueueService` and forwarded by `SignedQueueService`. Scope `admin:queues:read`.
+  - `admin:listIncomingWebhookReceipts` / `admin:getIncomingWebhookReceipt` expose received webhooks, backed by a new `IncomingWebhookService.getReceipt(receiptId)` (null by default; implemented by `KyselyIncomingWebhookService`). Scope `admin:webhooks:read`.
+
+  `@pikku/addon-console`:
+
+  - `console:variableGet` / `console:variableSet` read and write a project variable, gated on `pikku:console:variables:read` / `:write`.
+  - `console:runScenarios({ names?, environment? })` starts `pikku scenario run` as a detached child process and returns `{ runId }` to follow through `listScenarioRuns` / `getScenarioRun`, gated on the new `pikku:console:scenarios:run` scope. `pikku scenario run` takes `--run-id <id>` to record under a caller-chosen id.
+
+- Updated dependencies [de9af6a]
+  - @pikku/core@0.12.143
+
 ## 0.12.8
 
 ### Patch Changes

package/dist/bull-queue-service.d.ts

@@ -1,9 +1,10 @@
 import type { ConnectionOptions, JobsOptions } from 'bullmq';
 import type Bull from 'bullmq';
 import { Queue, QueueEvents } from 'bullmq';
-import type { QueueJob, QueueService } from '@pikku/core/queue';
+import type { QueueInspection, QueueJob, QueueJobRecord, QueueJobStatus, QueueService } from '@pikku/core/queue';
 import type { JobOptions } from '@pikku/core/queue';
 export declare const mapPikkuJobToBull: (options?: JobOptions) => JobsOptions;
+export declare const mapBullJobToRecord: (job: Bull.Job, status: QueueJobStatus) => QueueJobRecord;
 /**
  * Bull/Redis queue service implementation
  * Supports job results, retries, and most queue features
@@ -12,8 +13,8 @@ export declare class BullQueueService implements QueueService {
     private redisConnectionOptions;
     readonly name = "bull";
     readonly supportsResults = true;
-    protected queues: Map<string, Queue<any, any, string, any, any, string, Bull.RedisQueueBackend>>;
-    protected queueEvents: Map<string, QueueEvents<any>>;
+    protected queues: Map<string, Queue<any, any, string, any, any, string, Bull.RedisQueueBackend, ConnectionOptions>>;
+    protected queueEvents: Map<string, QueueEvents<any, Bull.RedisQueueBackend, ConnectionOptions>>;
     constructor(redisConnectionOptions?: ConnectionOptions);
     /**
      * Create a Bull queue with translated configuration
@@ -23,6 +24,9 @@ export declare class BullQueueService implements QueueService {
      * Add a job to the queue
      */
     add<In>(queueName: string, data: In, options?: JobOptions): Promise<string>;
+    inspect(queueName: string, opts?: {
+        limit?: number;
+    }): Promise<QueueInspection>;
     /**
      * Get job by ID
      */

package/dist/bull-queue-service.js

@@ -30,6 +30,24 @@ export const mapPikkuJobToBull = (options) => {
     }
     return bullOptions;
 };
+const INSPECTED_STATES = [
+    'waiting',
+    'active',
+    'delayed',
+    'completed',
+    'failed',
+];
+export const mapBullJobToRecord = (job, status) => ({
+    jobId: job.id,
+    status,
+    attemptsMade: job.attemptsMade,
+    maxAttempts: job.opts.attempts ?? 1,
+    createdAt: new Date(job.timestamp),
+    processedAt: job.processedOn ? new Date(job.processedOn) : null,
+    finishedAt: job.finishedOn ? new Date(job.finishedOn) : null,
+    durationMs: job.finishedOn && job.processedOn ? job.finishedOn - job.processedOn : null,
+    error: job.failedReason || null,
+});
 /**
  * Bull/Redis queue service implementation
  * Supports job results, retries, and most queue features
@@ -76,6 +94,16 @@ export class BullQueueService {
         }
         return bullJob.id;
     }
+    async inspect(queueName, opts) {
+        const queue = await this.createQueue(queueName);
+        const limit = opts?.limit ?? 50;
+        const counts = (await queue.getJobCounts(...INSPECTED_STATES));
+        const recent = (await Promise.all(INSPECTED_STATES.map(async (status) => (await queue.getJobs([status], 0, limit - 1)).map((job) => mapBullJobToRecord(job, status)))))
+            .flat()
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+            .slice(0, limit);
+        return { counts, recent };
+    }
     /**
      * Get job by ID
      */

package/knowledge/decisions/a-delayed-rpc-job-carries-the-callers-session-and-a-recurring-job-carries-none.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: A delayed RPC job carries the caller's session in its data, and a recurring job carries none
+description: BullSchedulerService stores the session in the job data and returns it from getTask, while the recurring worker runs the task by name alone
+tags: bullmq, scheduler, sessions, rpc
+---
+
+# A delayed RPC job carries the caller's session in its data, and a recurring job carries none
+
+`BullSchedulerService` in `packages/services/queue-bullmq/src/bull-scheduler-service.ts` defines the job data
+as `{ rpcName, data?, session? }` (lines 17-21).
+
+**Delayed.** `scheduleRPC` takes an optional `session` (line 56) and puts it in the job data (lines 62-66). The
+job is added to the `pikku-remote-internal-rpc` queue with the delay (lines 69-72). `getTask` returns the stored
+`session` (line 116). `getAllTasks` returns only the id, rpc name and time (lines 133-137). The session is
+therefore stored in Redis with the job.
+
+**What runs it.** This file has no worker for that queue. The CLI generates one, `remoteRPCHandler`, whose
+function destructures only `{ rpcName, data }` and calls `rpc.invoke(rpcName, data)`
+(`packages/cli/src/functions/wirings/rpc/serialize-remote-rpc.ts:37-39`). It is wired to the queue at lines
+43-47 of the same file. Nothing in that handler reads the job's `session`.
+
+**Recurring.** `start` creates a worker on `pikku-recurring-scheduled-task` (lines 161-169) that calls
+`runScheduledTask({ name: rpcName })` (line 166). The job data written for each task is `{ rpcName: name }`
+(line 179), so there is no session to carry.
+
+The same question for the in-memory scheduler is open in
+[does-a-delayed-rpc-run-as-the-session-it-was-scheduled-with](../../../../core/knowledge/questions/does-a-delayed-rpc-run-as-the-session-it-was-scheduled-with.md).
+
+**What this rules out:** reading `getTask().session` as evidence that the delayed run executes as that user,
+and putting anything secret in a session passed to `scheduleRPC`, since it is stored in the job data.

package/knowledge/decisions/index.md

@@ -0,0 +1,12 @@
+---
+type: overview
+title: Decisions
+---
+
+# Decisions
+
+A rule that was chosen, and what it rules out.
+
+<!-- pikku:knowledge-index -->
+- [A delayed RPC job carries the caller's session in its data, and a recurring job carries none](a-delayed-rpc-job-carries-the-callers-session-and-a-recurring-job-carries-none.md) — BullSchedulerService stores the session in the job data and returns it from getTask, while the recurring worker runs the task by name alone
+<!-- /pikku:knowledge-index -->

package/knowledge/index.md

@@ -0,0 +1,13 @@
+---
+type: overview
+title: Knowledge
+description: What identity a BullMQ job carries when it runs
+---
+
+# Knowledge
+
+The BullMQ scheduler runs delayed and recurring jobs. These notes record which of them carry a caller's session.
+
+<!-- pikku:knowledge-index -->
+- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
+<!-- /pikku:knowledge-index -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/queue-bullmq",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -21,7 +21,7 @@
     "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.108"
+    "@pikku/core": "^0.12.143"
   },
   "dependencies": {
     "bullmq": "^6.1.1",