@pikku/core 0.7.0 → 0.7.1

package/src/pikku-state.ts

@@ -0,0 +1,87 @@
+import { ChannelsMeta, CoreAPIChannel } from './channel/channel.types.js'
+import {
+  CoreHTTPFunctionRoute,
+  HTTPMethod,
+  HTTPRoutesMeta,
+} from './http/http.types.js'
+import { FunctionsMeta, PikkuMiddleware } from './types/core.types.js'
+import {
+  CoreScheduledTask,
+  ScheduledTasksMeta,
+} from './scheduler/scheduler.types.js'
+import { ErrorDetails, PikkuError } from './errors/error-handler.js'
+import {
+  CoreAPIFunction,
+  CoreAPIFunctionSessionless,
+} from './function/functions.types.js'
+
+interface PikkuState {
+  functions: {
+    meta: FunctionsMeta
+    nameToFunction: Map<
+      string,
+      CoreAPIFunction<any, any> | CoreAPIFunctionSessionless<any, any>
+    >
+  }
+  http: {
+    middleware: Array<{ route: string; middleware: PikkuMiddleware[] }>
+    routes: Map<HTTPMethod, Map<string, CoreHTTPFunctionRoute<any, any, any>>>
+    meta: HTTPRoutesMeta
+  }
+  channel: {
+    channels: Map<string, CoreAPIChannel<any, any>>
+    meta: ChannelsMeta
+  }
+  scheduler: {
+    tasks: Map<string, CoreScheduledTask>
+    meta: ScheduledTasksMeta
+  }
+  misc: {
+    errors: Map<PikkuError, ErrorDetails>
+    schemas: Map<string, any>
+  }
+}
+
+export const resetPikkuState = () => {
+  globalThis.pikkuState = {
+    functions: {
+      meta: {},
+      nameToFunction: new Map(),
+    },
+    http: {
+      middleware: [],
+      routes: new Map(),
+      meta: [],
+    },
+    channel: {
+      channels: new Map(),
+      meta: {},
+    },
+    scheduler: {
+      tasks: new Map(),
+      meta: [],
+    },
+    misc: {
+      errors: globalThis.pikkuState?.misc?.errors || new Map(),
+      schemas: globalThis.pikkuState?.misc?.schema || new Map(),
+    },
+  }
+}
+
+if (!globalThis.pikkuState) {
+  resetPikkuState()
+}
+
+export const pikkuState = <
+  Type extends keyof PikkuState,
+  Content extends keyof PikkuState[Type],
+>(
+  type: Type,
+  content: Content,
+  value?: PikkuState[Type][Content]
+): PikkuState[Type][Content] => {
+  if (value) {
+    globalThis.pikkuState[type][content] = value
+  }
+  return globalThis.pikkuState[type][content]
+}

package/src/scheduler/index.ts

@@ -0,0 +1,5 @@
+export * from './scheduler.types.js'
+
+export { runScheduledTask, addScheduledTask } from './scheduler-runner.js'
+
+export * from './log-schedulers.js'

package/src/scheduler/log-schedulers.ts

@@ -0,0 +1,20 @@
+import { pikkuState } from '../pikku-state.js'
+import { Logger } from '../services/index.js'
+
+/**
+ * Logs all the loaded scheduled tasks.
+ * @param logger - A logger for logging information.
+ */
+export const logSchedulers = (logger: Logger) => {
+  const scheduledTasks = pikkuState('scheduler', 'tasks')
+  if (scheduledTasks.size === 0) {
+    logger.info('No scheduled tasks added')
+    return
+  }
+
+  let scheduledTasksMessage = 'Scheduled tasks:'
+  scheduledTasks.forEach(({ schedule }, name) => {
+    scheduledTasksMessage += `\n\t- ${name} -> ${schedule}`
+  })
+  logger.info(scheduledTasksMessage)
+}

package/src/scheduler/scheduler-runner.ts

@@ -0,0 +1,105 @@
+import type {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+} from '../types/core.types.js'
+import type { CoreScheduledTask } from './scheduler.types.js'
+import type { CoreAPIFunctionSessionless } from '../function/functions.types.js'
+import { getErrorResponse } from '../errors/error-handler.js'
+import { closeSessionServices } from '../utils.js'
+import { pikkuState } from '../pikku-state.js'
+import { addFunction, runPikkuFunc } from '../function/function-runner.js'
+
+export type RunScheduledTasksParams = {
+  name: string
+  session?: CoreUserSession
+  singletonServices: CoreSingletonServices
+  createSessionServices?: CreateSessionServices<
+    CoreSingletonServices,
+    CoreServices<CoreSingletonServices>,
+    CoreUserSession
+  >
+}
+
+export const addScheduledTask = <
+  APIFunction extends CoreAPIFunctionSessionless<void, void>,
+>(
+  scheduledTask: CoreScheduledTask<APIFunction>
+) => {
+  const meta = pikkuState('scheduler', 'meta')
+  const taskMeta = meta[scheduledTask.name]
+  if (!taskMeta) {
+    throw new Error('Task metadata not found')
+  }
+  addFunction(taskMeta.pikkuFuncName, scheduledTask.func)
+
+  const tasks = pikkuState('scheduler', 'tasks')
+  if (tasks.has(scheduledTask.name)) {
+    throw new Error(`Scheduled task already exists: ${scheduledTask.name}`)
+  }
+  tasks.set(scheduledTask.name, scheduledTask)
+}
+
+class ScheduledTaskNotFoundError extends Error {
+  constructor(title: string) {
+    super(`Scheduled task not found: ${title}`)
+  }
+}
+
+export async function runScheduledTask<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+>({
+  name,
+  session,
+  singletonServices,
+  createSessionServices,
+}: RunScheduledTasksParams): Promise<void> {
+  let sessionServices: CoreServices | undefined
+  try {
+    const task = pikkuState('scheduler', 'tasks').get(name)
+    const meta = pikkuState('scheduler', 'meta')[name]
+    if (!task) {
+      throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`)
+    }
+    if (!meta) {
+      throw new ScheduledTaskNotFoundError(
+        `Scheduled task meta not found: ${name}`
+      )
+    }
+
+    singletonServices.logger.info(
+      `Running schedule task: ${name} | schedule: ${task.schedule}`
+    )
+
+    const getAllServices = async () => {
+      if (createSessionServices) {
+        const sessionServices = await createSessionServices(
+          singletonServices,
+          {},
+          session
+        )
+        return { ...singletonServices, ...sessionServices }
+      }
+      return singletonServices
+    }
+
+    return await runPikkuFunc(meta.pikkuFuncName, {
+      singletonServices,
+      getAllServices,
+      session,
+      data: undefined,
+    })
+  } catch (e: any) {
+    const errorResponse = getErrorResponse(e)
+    if (errorResponse != null) {
+      singletonServices.logger.error(e)
+    }
+    throw e
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
+}

package/src/scheduler/scheduler.types.ts

@@ -0,0 +1,33 @@
+import { APIDocs, CoreUserSession } from '../types/core.types.js'
+import { CoreAPIFunctionSessionless } from '../function/functions.types.js'
+
+/**
+ * Represents metadata for scheduled tasks, including title, schedule, and documentation.
+ */
+export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
+  Record<
+    string,
+    {
+      pikkuFuncName: string
+      name: string
+      schedule: string
+      session?: UserSession
+      docs?: APIDocs
+      tags?: string[]
+    }
+  >
+
+/**
+ * Represents a core scheduled task.
+ */
+export type CoreScheduledTask<
+  APIFunction = CoreAPIFunctionSessionless<void, void>,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = {
+  name: string
+  schedule: string
+  func: APIFunction
+  docs?: APIDocs
+  session?: UserSession
+  tags?: string[]
+}

package/src/schema.test.ts

@@ -0,0 +1,57 @@
+import { test, describe, before } from 'node:test'
+import * as assert from 'assert'
+import { addSchema, coerceTopLevelDataFromSchema } from './schema.js'
+
+describe('Schema', () => {
+  describe('coerceQueryStringToArray', () => {
+    before(() => {
+      // Add schemas dynamically using addSchema
+      addSchema('testSchema', {
+        properties: {
+          tags: { type: 'array' },
+          count: { type: 'number' },
+          name: { type: 'string' },
+        },
+      })
+
+      addSchema('booleanSchema', {
+        properties: {
+          isActive: true, // Invalid schema definition, but the function should handle it
+          tags: { type: 'array' },
+        },
+      })
+    })
+
+    test('should split a string into an array for properties of type array', () => {
+      const data = { tags: 'a,b,c' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties of type array if they are already arrays', () => {
+      const data = { tags: ['a', 'b', 'c'] }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+    })
+
+    test('should not modify properties that are not type array', () => {
+      const data = { count: 5, name: 'example' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.strictEqual(data.count, 5)
+      assert.strictEqual(data.name, 'example')
+    })
+
+    test('should handle cases where the data object does not have a key present in the schema', () => {
+      const data = { unknownKey: 'shouldRemain' }
+      coerceTopLevelDataFromSchema('testSchema', data)
+      assert.strictEqual(data.unknownKey, 'shouldRemain')
+    })
+
+    test('should handle cases where schema properties contain boolean values', () => {
+      const data = { tags: 'a,b,c', isActive: 'true' }
+      coerceTopLevelDataFromSchema('booleanSchema', data)
+      assert.deepStrictEqual(data.tags, ['a', 'b', 'c'])
+      assert.strictEqual(data.isActive, 'true') // No coercion should happen
+    })
+  })
+})

package/src/schema.ts

@@ -0,0 +1,99 @@
+import { Logger } from './services/logger.js'
+import { SchemaService } from './services/schema-service.js'
+import { UnprocessableContentError } from './errors/errors.js'
+import { pikkuState } from './pikku-state.js'
+
+/**
+ * Adds a schema to the global schemas map.
+ * @param name - The name of the schema.
+ * @param value - The schema value.
+ * @ignore
+ */
+export const addSchema = (name: string, value: any) => {
+  pikkuState('misc', 'schemas').set(name, value)
+}
+
+/**
+ * Loads a schema and compiles it into a validator.
+ * @param logger - A logger for logging information.
+ */
+export const compileAllSchemas = (
+  logger: Logger,
+  schemaService?: SchemaService
+) => {
+  if (!schemaService) {
+    throw new Error('SchemaService needs to be defined to load schemas')
+  }
+  const schemas = pikkuState('misc', 'schemas')
+  for (const [name, schema] of schemas) {
+    schemaService.compileSchema(name, schema)
+  }
+  validateAllSchemasLoaded(logger, schemaService)
+}
+
+const validateAllSchemasLoaded = (
+  logger: Logger,
+  schemaService: SchemaService
+) => {
+  const routesMeta = pikkuState('http', 'meta')
+  const validators = schemaService.getSchemaNames()
+
+  const missingSchemas: string[] = []
+
+  for (const route of routesMeta) {
+    if (!route.input || validators.has(route.input)) {
+      continue
+    }
+    missingSchemas.push(route.input)
+  }
+
+  if (missingSchemas.length > 0) {
+    logger.error(
+      `Error: Failed to load schemas:\n.${missingSchemas.join('\n')}`
+    )
+    logger.error('\tHave you run the schema generation?')
+    logger.error('\tnpx @pikku/cli schemas')
+  } else {
+    logger.info('All schemas loaded')
+  }
+}
+
+export const coerceTopLevelDataFromSchema = (schemaName: string, data: any) => {
+  const schema = pikkuState('misc', 'schemas').get(schemaName)
+  for (const key in schema.properties) {
+    const property = schema.properties[key]
+    if (typeof property === 'boolean') {
+      continue
+    }
+    const type = property.type
+    if (typeof type === 'boolean') {
+      continue
+    }
+    if (type === 'array' && typeof data[key] === 'string') {
+      data[key] = data[key].split(',')
+    } else if (type === 'string' && property.format === 'date-time') {
+      data[key] = new Date(data[key])
+    }
+  }
+}
+
+export const validateSchema = async (
+  logger: Logger,
+  schemaService: SchemaService | undefined,
+  schemaName: string | undefined | null,
+  data: any
+) => {
+  if (schemaService) {
+    if (!schemaName) {
+      if (data && (data.length > 0 || Object.keys(data).length > 0)) {
+        logger.warn('No schema provided, but data was passed')
+        throw new UnprocessableContentError('No data expected')
+      } else {
+        return
+      }
+    }
+    const schema = pikkuState('misc', 'schemas').get(schemaName)
+    await schemaService.compileSchema(schemaName, schema)
+    await schemaService.validateSchema(schemaName, data)
+  }
+}

package/src/services/content-service.ts

@@ -0,0 +1,68 @@
+import { ReadStream } from 'fs'
+
+export interface ContentService {
+  /**
+   * 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>
+
+  /**
+   * 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>
+
+  /**
+   * 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.
+   */
+  getUploadURL(
+    fileKey: string,
+    contentType: string
+  ): Promise<{ uploadUrl: string; assetKey: string }>
+
+  /**
+   * 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>
+
+  /**
+   * 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.
+   */
+  writeFile(assetKey: string, stream: ReadStream): 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.
+   */
+  copyFile(assetKey: string, fromAbsolutePath: string): 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<ReadStream>
+}

package/src/services/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @module @pikku/core
+ */
+
+// Interfaces
+export * from './content-service.js'
+export * from './jwt-service.js'
+export * from './logger.js'
+export * from './logger-console.js'
+export * from './secret-service.js'
+export * from './variables-service.js'
+export * from './schema-service.js'
+export * from './user-session-service.js'
+export * from './local-content.js'
+
+// Local implementations
+export * from './local-secrets.js'
+export * from './local-variables.js'

package/src/services/jwt-service.ts

@@ -0,0 +1,30 @@
+import { RelativeTimeInput } from '../time-utils.js'
+
+/**
+ * Interface for handling JSON Web Tokens (JWT).
+ */
+export interface JWTService {
+  /**
+   * Encodes a payload into a JWT.
+   * @param expiresIn - The expiration time of the token.
+   * @param payload - The payload to encode.
+   * @returns A promise that resolves to the encoded JWT.
+   */
+  encode: <T extends any>(
+    expiresIn: RelativeTimeInput,
+    payload: T
+  ) => Promise<string>
+
+  /**
+   * Decodes a JWT into its payload.
+   * @param hash - The JWT to decode.
+   * @param invalidHashError - An optional error to throw if the hash is invalid.
+   * @param debug - An optional flag for debugging.
+   * @returns A promise that resolves to the decoded payload.
+   */
+  decode: <T>(
+    hash: string,
+    invalidHashError?: Error,
+    debug?: boolean
+  ) => Promise<T>
+}

package/src/services/local-content.ts

@@ -0,0 +1,105 @@
+import { createReadStream, createWriteStream, promises, ReadStream } from 'fs'
+import { mkdir } from 'fs/promises'
+import { ContentService, Logger } from '@pikku/core/services'
+import { pipeline } from 'stream/promises'
+import { Readable } from 'stream'
+
+export interface LocalContentConfig {
+  localFileUploadPath: string
+  uploadUrlPrefix: string
+  assetUrlPrefix: string
+  sizeLimit?: string
+}
+
+export class LocalContent implements ContentService {
+  constructor(
+    private config: LocalContentConfig,
+    private logger: Logger
+  ) {}
+
+  public async init() {}
+
+  public async signURL(url: string): Promise<string> {
+    return `${url}?signed=true`
+  }
+
+  public async signContentKey(assetKey: string): Promise<string> {
+    return `${this.config.assetUrlPrefix}/${assetKey}?signed=true`
+  }
+
+  public async getUploadURL(assetKey: string) {
+    this.logger.debug(`Going to upload with key: ${assetKey}`)
+    return {
+      uploadUrl: `${this.config.uploadUrlPrefix}/${assetKey}`,
+      assetKey,
+    }
+  }
+
+  public async writeFile(assetKey: string, stream: Readable): Promise<boolean> {
+    this.logger.debug(`Writing file: ${assetKey}`)
+
+    const path = `${this.config.localFileUploadPath}/${assetKey}`
+
+    try {
+      await this.createDirectoryForFile(path)
+      const fileStream = createWriteStream(path)
+      // Use pipeline to properly manage stream piping and errors
+      await pipeline(stream, fileStream)
+      return true
+    } catch (e) {
+      console.error(e)
+      this.logger.error(`Error writing content ${assetKey}`, e)
+      return false
+    }
+  }
+
+  public async copyFile(
+    assetKey: string,
+    fromAbsolutePath: string
+  ): Promise<boolean> {
+    this.logger.debug(`Writing file: ${assetKey}`)
+    try {
+      const path = `${this.config.localFileUploadPath}/${assetKey}`
+      await this.createDirectoryForFile(path)
+      await promises.copyFile(fromAbsolutePath, path)
+    } catch (e) {
+      console.error(e)
+      this.logger.error(`Error inserting content ${assetKey}`, e)
+    }
+    return false
+  }
+
+  public async readFile(assetKey: string): Promise<ReadStream> {
+    this.logger.debug(`Getting key: ${assetKey}`)
+
+    const filePath = `${this.config.localFileUploadPath}/${assetKey}`
+
+    try {
+      const stream = createReadStream(filePath)
+      // Handle early stream errors (like file not found, permission denied, etc.)
+      stream.on('error', (err) => {
+        this.logger.error(`Error getting content ${assetKey}`, err)
+      })
+
+      return stream
+    } catch (e) {
+      this.logger.error(`Error setting up stream for ${assetKey}`, e)
+      throw e
+    }
+  }
+
+  public async deleteFile(assetKey: string): Promise<boolean> {
+    this.logger.debug(`deleting key: ${assetKey}`)
+    try {
+      await promises.unlink(`${this.config.localFileUploadPath}/${assetKey}`)
+    } catch (e: any) {
+      this.logger.error(`Error deleting content ${assetKey}`, e)
+    }
+    return false
+  }
+
+  private async createDirectoryForFile(path: string): Promise<void> {
+    const dir = path.split('/').slice(0, -1).join('/')
+    await mkdir(dir, { recursive: true })
+  }
+}

package/src/services/local-secrets.ts

@@ -0,0 +1,43 @@
+import { LocalVariablesService } from './local-variables.js'
+import { SecretService } from './secret-service.js'
+import { VariablesService } from './variables-service.js'
+
+/**
+ * Service for retrieving secrets from environment variables.
+ */
+export class LocalSecretService implements SecretService {
+  /**
+   * Creates an instance of LocalSecretService.
+   */
+  constructor(
+    private variables: VariablesService = new LocalVariablesService()
+  ) {}
+
+  /**
+   * Retrieves a secret by key.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   * @throws {Error} If the secret is not found.
+   */
+  public async getSecretJSON<R>(key: string): Promise<R> {
+    const value = await this.variables.get(key)
+    if (value) {
+      return JSON.parse(value)
+    }
+    throw new Error(`Secret Not Found: ${key}`)
+  }
+
+  /**
+   * Retrieves a secret by key.
+   * @param key - The key of the secret to retrieve.
+   * @returns A promise that resolves to the secret value.
+   * @throws {Error} If the secret is not found.
+   */
+  public async getSecret(key: string): Promise<string> {
+    const value = await this.variables.get(key)
+    if (value) {
+      return value
+    }
+    throw new Error(`Secret Not Found: ${key}`)
+  }
+}

package/src/services/local-variables.ts

@@ -0,0 +1,17 @@
+import { VariablesService } from './variables-service.js'
+
+export class LocalVariablesService implements VariablesService {
+  constructor(
+    private variables: Record<string, string | undefined> = process.env
+  ) {}
+
+  public getAll():
+    | Promise<Record<string, string | undefined>>
+    | Record<string, string | undefined> {
+    return this.variables || {}
+  }
+
+  public get(name: string): Promise<string | undefined> | string | undefined {
+    return this.variables[name]
+  }
+}