@pikku/core 0.12.19 → 0.12.21

package/src/services/content-service.ts

@@ -1,81 +1,109 @@
-export interface ContentService {
+/**
+ * Arguments for signing a content key into a time-limited URL.
+ */
+export interface SignContentKeyArgs<TBucket extends string = string> {
+  bucket: TBucket
+  contentKey: string
+  dateLessThan: Date
+  dateGreaterThan?: Date
+}
+
+/**
+ * Arguments for signing an arbitrary URL.
+ */
+export interface SignURLArgs {
+  url: string
+  dateLessThan: Date
+  dateGreaterThan?: Date
+}
+
+/**
+ * Arguments for minting a presigned upload URL.
+ */
+export interface GetUploadURLArgs<TBucket extends string = string> {
+  bucket: TBucket
+  fileKey: string
+  contentType: string
+  size?: number
+}
+
+/**
+ * Result of minting a presigned upload URL.
+ */
+export interface UploadURLResult {
+  uploadUrl: string
+  assetKey: string
+  uploadHeaders?: Record<string, string>
+  uploadMethod?: 'PUT' | 'POST'
+}
+
+/**
+ * Arguments for an operation that targets a single object by key.
+ */
+export interface BucketKeyArgs<TBucket extends string = string> {
+  bucket: TBucket
+  key: string
+}
+
+/**
+ * Arguments for writing a stream to storage.
+ */
+export interface WriteFileArgs<
+  TBucket extends string = string,
+> extends BucketKeyArgs<TBucket> {
+  stream: ReadableStream | NodeJS.ReadableStream
+}
+
+/**
+ * Arguments for copying a local file into storage.
+ */
+export interface CopyFileArgs<
+  TBucket extends string = string,
+> extends BucketKeyArgs<TBucket> {
+  fromAbsolutePath: string
+}
+
+export interface ContentService<TBucket extends string = string> {
   /**
    * Signs a content key to generate a secure, time-limited access URL.
-   * @param contentKey - The key representing the content object.
-   * @param dateLessThan - The expiration time for the signed URL.
-   * @param dateGreaterThan - (Optional) Start time before which access is denied.
    */
-  signContentKey(
-    contentKey: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string>
+  signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>
 
   /**
    * Signs an arbitrary URL to generate a secure, time-limited access URL.
-   * @param url - The full URL that needs signing.
-   * @param dateLessThan - The expiration time for the signed URL.
-   * @param dateGreaterThan - (Optional) Start time before which access is denied.
    */
-  signURL(
-    url: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string>
+  signURL(args: SignURLArgs): Promise<string>
 
   /**
    * Generates a signed URL for uploading a file directly to storage.
-   * @param fileKey - The desired key/location of the uploaded file.
-   * @param contentType - The MIME type of the file.
-   * @returns A signed upload URL and the finalized asset key.
+   * Bucket policy (size limits, MIME allowlist) is enforced by the implementation.
    */
-  getUploadURL(
-    fileKey: string,
-    contentType: string
-  ): Promise<{
-    uploadUrl: string
-    assetKey: string
-    uploadHeaders?: Record<string, string>
-    uploadMethod?: 'PUT' | 'POST'
-  }>
+  getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>
 
   /**
    * Deletes a file from the storage backend.
-   * @param fileName - The name or key of the file to delete.
-   * @returns A boolean indicating success.
    */
-  deleteFile(fileName: string): Promise<boolean>
+  deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>
 
   /**
-   * Uploads a file stream to storage under a specified asset key.
-   * @param assetKey - The key where the file will be saved.
-   * @param stream - A readable stream of the file contents.
-   * @returns A boolean indicating success.
+   * Uploads a file stream to storage under the specified bucket + key.
    */
-  writeFile(
-    assetKey: string,
-    stream: ReadableStream | NodeJS.ReadableStream
-  ): Promise<boolean>
+  writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>
 
   /**
-   * Copies a file from a local absolute path into storage under a new asset key.
-   * @param assetKey - The destination key.
-   * @param fromAbsolutePath - The local absolute file path.
-   * @returns A boolean indicating success.
+   * Copies a file from a local absolute path into storage.
    */
-  copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>
+  copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>
 
   /**
    * Reads a file from storage as a readable stream.
-   * @param assetKey - The key of the file to read.
-   * @returns A readable file stream.
    */
-  readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>
+  readFile(
+    args: BucketKeyArgs<TBucket>
+  ): Promise<ReadableStream | NodeJS.ReadableStream>
 
   /**
    * Reads an entire file from storage into a Buffer.
-   * @param assetKey - The key of the file to read.
-   * @returns The file contents as a Buffer.
    */
-  readFileAsBuffer(assetKey: string): Promise<Buffer>
+  readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>
 }

package/src/services/in-memory-queue-service.ts

@@ -24,7 +24,7 @@ export class InMemoryQueueService implements QueueService {
       pikkuUserId: options?.pikkuUserId,
     }
 
-    const delay = options?.delay ?? 0
+    const delay = options?.delay ?? 100 + Math.floor(Math.random() * 201)
 
     setTimeout(async () => {
       try {

package/src/services/in-memory-session-store.ts

@@ -3,8 +3,7 @@ import type { SessionStore } from './session-store.js'
 
 export class InMemorySessionStore<
   UserSession extends CoreUserSession = CoreUserSession,
-> implements SessionStore<UserSession>
-{
+> implements SessionStore<UserSession> {
   private sessions = new Map<string, UserSession>()
 
   async get(pikkuUserId: string): Promise<UserSession | undefined> {

package/src/services/in-memory-workflow-service.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert'
 import { InMemoryWorkflowService } from './in-memory-workflow-service.js'
+import { getQueueWorkers } from '../wirings/queue/queue-runner.js'
+import { pikkuState } from '../pikku-state.js'
 
 let service: InMemoryWorkflowService
 
@@ -48,17 +50,10 @@ describe('InMemoryWorkflowService', () => {
     })
 
     test('should persist deterministic planned steps metadata', async () => {
-      const runId = await service.createRun(
-        'wf',
-        {},
-        true,
-        'h',
-        {} as any,
-        {
-          deterministic: true,
-          plannedSteps: [{ stepName: 'Step 1' }, { stepName: 'Step 2' }],
-        }
-      )
+      const runId = await service.createRun('wf', {}, true, 'h', {} as any, {
+        deterministic: true,
+        plannedSteps: [{ stepName: 'Step 1' }, { stepName: 'Step 2' }],
+      })
 
       const run = await service.getRun(runId)
       assert.strictEqual(run?.deterministic, true)
@@ -369,4 +364,31 @@ describe('InMemoryWorkflowService', () => {
       assert.deepStrictEqual(history, [])
     })
   })
+
+  describe('queue worker registration', () => {
+    test('rewireQueueWorkers registers workflow queues added after construction', () => {
+      const stepQueue = 'wf-step-regression-enrich'
+      const orchQueue = 'wf-orchestrator-regression-onboarding'
+
+      const ws = new InMemoryWorkflowService()
+
+      const queueMeta = pikkuState(null, 'queue', 'meta')
+      queueMeta[stepQueue] = {
+        name: stepQueue,
+        pikkuFuncId: 'pikkuWorkflowWorker:regressionEnrich',
+      }
+      queueMeta[orchQueue] = {
+        name: orchQueue,
+        pikkuFuncId: 'pikkuWorkflowOrchestrator:regressionOnboarding',
+      }
+
+      assert.strictEqual(getQueueWorkers().has(stepQueue), false)
+      assert.strictEqual(getQueueWorkers().has(orchQueue), false)
+
+      ws.rewireQueueWorkers()
+
+      assert.strictEqual(getQueueWorkers().has(stepQueue), true)
+      assert.strictEqual(getQueueWorkers().has(orchQueue), true)
+    })
+  })
 })

package/src/services/in-memory-workflow-service.ts

@@ -37,6 +37,7 @@ export class InMemoryWorkflowService
   extends PikkuWorkflowService
   implements WorkflowRunService
 {
+  private sleepTimers = new Set<ReturnType<typeof setTimeout>>()
   private runs = new Map<string, WorkflowRun>()
   private steps = new Map<string, StepState>() // keyed by `${runId}:${stepName}`
   private stepData = new Map<string, InternalStepData>() // keyed by stepId
@@ -51,7 +52,7 @@ export class InMemoryWorkflowService
     { graph: any; source: string; status: WorkflowVersionStatus }
   >() // keyed by `${name}:${graphHash}`
 
-  async createRun(
+  protected async createRunImpl(
     workflowName: string,
     input: any,
     inline: boolean,
@@ -90,6 +91,25 @@ export class InMemoryWorkflowService
     return runId
   }
 
+  protected override async scheduleSleep(
+    runId: string,
+    stepId: string,
+    duration: number
+  ): Promise<boolean> {
+    const timer = setTimeout(async () => {
+      this.sleepTimers.delete(timer)
+      try {
+        await this.executeWorkflowSleepCompleted(runId, stepId)
+      } catch (error: any) {
+        this.logger?.error(
+          `Failed to resume workflow sleep for runId ${runId}: ${error?.message ?? error}`
+        )
+      }
+    }, duration)
+    this.sleepTimers.add(timer)
+    return true
+  }
+
   async getRun(id: string): Promise<WorkflowRun | null> {
     return this.runs.get(id) || null
   }
@@ -100,7 +120,7 @@ export class InMemoryWorkflowService
     return this.stepHistory.get(runId) || []
   }
 
-  async updateRunStatus(
+  protected async updateRunStatusImpl(
     id: string,
     status: WorkflowStatus,
     output?: any,
@@ -115,7 +135,7 @@ export class InMemoryWorkflowService
     }
   }
 
-  async insertStepState(
+  protected async insertStepStateImpl(
     runId: string,
     stepName: string,
     rpcName: string | null,
@@ -159,7 +179,7 @@ export class InMemoryWorkflowService
     return step
   }
 
-  async setStepRunning(stepId: string): Promise<void> {
+  protected async setStepRunningImpl(stepId: string): Promise<void> {
     for (const step of this.steps.values()) {
       if (step.stepId === stepId) {
         step.status = 'running'
@@ -170,7 +190,7 @@ export class InMemoryWorkflowService
     }
   }
 
-  async setStepScheduled(stepId: string): Promise<void> {
+  protected async setStepScheduledImpl(stepId: string): Promise<void> {
     for (const step of this.steps.values()) {
       if (step.stepId === stepId) {
         step.status = 'scheduled'
@@ -181,7 +201,10 @@ export class InMemoryWorkflowService
     }
   }
 
-  async setStepResult(stepId: string, result: any): Promise<void> {
+  protected async setStepResultImpl(
+    stepId: string,
+    result: any
+  ): Promise<void> {
     for (const step of this.steps.values()) {
       if (step.stepId === stepId) {
         step.status = 'succeeded'
@@ -193,7 +216,10 @@ export class InMemoryWorkflowService
     }
   }
 
-  async setStepError(stepId: string, error: Error): Promise<void> {
+  protected async setStepErrorImpl(
+    stepId: string,
+    error: Error
+  ): Promise<void> {
     for (const step of this.steps.values()) {
       if (step.stepId === stepId) {
         step.status = 'failed'
@@ -209,7 +235,10 @@ export class InMemoryWorkflowService
     }
   }
 
-  async setStepChildRunId(stepId: string, childRunId: string): Promise<void> {
+  protected async setStepChildRunIdImpl(
+    stepId: string,
+    childRunId: string
+  ): Promise<void> {
     for (const step of this.steps.values()) {
       if (step.stepId === stepId) {
         step.childRunId = childRunId
@@ -219,7 +248,7 @@ export class InMemoryWorkflowService
     }
   }
 
-  async createRetryAttempt(
+  protected async createRetryAttemptImpl(
     failedStepId: string,
     status: 'pending' | 'running'
   ): Promise<StepState> {
@@ -354,6 +383,10 @@ export class InMemoryWorkflowService
   }
 
   async close(): Promise<void> {
+    for (const timer of this.sleepTimers) {
+      clearTimeout(timer)
+    }
+    this.sleepTimers.clear()
     // Clear all in-memory state
     this.runs.clear()
     this.steps.clear()
@@ -439,11 +472,14 @@ export class InMemoryWorkflowService
     }
   }
 
-  async setBranchTaken(stepId: string, branchKey: string): Promise<void> {
+  protected async setBranchTakenImpl(
+    stepId: string,
+    branchKey: string
+  ): Promise<void> {
     this.branchKeys.set(stepId, branchKey)
   }
 
-  async updateRunState(
+  protected async updateRunStateImpl(
     runId: string,
     name: string,
     value: unknown
@@ -457,7 +493,7 @@ export class InMemoryWorkflowService
     return this.runState.get(runId) || {}
   }
 
-  async upsertWorkflowVersion(
+  protected async upsertWorkflowVersionImpl(
     name: string,
     graphHash: string,
     graph: any,
@@ -471,7 +507,7 @@ export class InMemoryWorkflowService
     })
   }
 
-  async updateWorkflowVersionStatus(
+  protected async updateWorkflowVersionStatusImpl(
     name: string,
     graphHash: string,
     status: WorkflowVersionStatus

package/src/services/index.ts

@@ -25,7 +25,16 @@ export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
 export { LocalGatewayService } from './local-gateway-service.js'
-export type { ContentService } from './content-service.js'
+export type {
+  ContentService,
+  SignContentKeyArgs,
+  SignURLArgs,
+  GetUploadURLArgs,
+  UploadURLResult,
+  BucketKeyArgs,
+  WriteFileArgs,
+  CopyFileArgs,
+} from './content-service.js'
 export type { JWTService } from './jwt-service.js'
 export type { Logger } from './logger.js'
 export type { SecretService } from './secret-service.js'

package/src/services/local-content.test.ts

@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { LocalContent } from './local-content.js'
+
+describe('LocalContent signing', () => {
+  test('binds notBefore into the signature payload', async () => {
+    let capturedPayload:
+      | { signedAt: number; expiresAt: number; notBefore?: number }
+      | undefined
+
+    const content = new LocalContent(
+      {
+        localFileUploadPath: '/tmp/uploads',
+        uploadUrlPrefix: '/reaper',
+        assetUrlPrefix: '/assets',
+        server: 'http://localhost:3000',
+      },
+      {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+        setLevel: () => {},
+      } as any,
+      {
+        encode: async (_expiresIn: any, payload: any) => {
+          capturedPayload = payload
+          return 'signed-token'
+        },
+        decode: async () => ({}),
+      }
+    )
+
+    const dateGreaterThan = new Date(Date.now() + 60_000)
+    const dateLessThan = new Date(Date.now() + 120_000)
+    const signedUrl = await content.signContentKey({
+      bucket: 'avatars',
+      contentKey: 'user-1.png',
+      dateLessThan,
+      dateGreaterThan,
+    })
+
+    const url = new URL(signedUrl)
+    assert.equal(url.searchParams.get('signature'), 'signed-token')
+    assert.ok(capturedPayload)
+    assert.equal(capturedPayload?.expiresAt, dateLessThan.getTime())
+    assert.equal(capturedPayload?.notBefore, dateGreaterThan.getTime())
+    assert.equal(
+      url.searchParams.get('notBefore'),
+      String(dateGreaterThan.getTime())
+    )
+  })
+})