@platformatic/next 3.4.1 → 3.5.0

package/lib/caching/valkey.js

@@ -0,0 +1,382 @@
+import { buildPinoFormatters, buildPinoTimestamp, ensureLoggableError } from '@platformatic/foundation'
+import { Redis } from 'iovalkey'
+import { pack, unpack } from 'msgpackr'
+import { existsSync, readFileSync } from 'node:fs'
+import { hostname } from 'node:os'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { pino } from 'pino'
+
+const CACHE_HIT_METRIC = { name: 'next_cache_valkey_hit_count', help: 'Next.js Cache (Valkey) Hit Count' }
+const CACHE_MISS_METRIC = { name: 'next_cache_valkey_miss_count', help: 'Next.js Cache (Valkey) Miss Count' }
+
+const clients = new Map()
+
+export const MAX_BATCH_SIZE = 100
+
+export const sections = {
+  values: 'values',
+  tags: 'tags'
+}
+
+export function keyFor (prefix, subprefix, section, key) {
+  return [prefix, 'cache:next', subprefix, section, key ? Buffer.from(key).toString('base64url') : undefined]
+    .filter(c => c)
+    .join(':')
+}
+
+export function getConnection (url) {
+  let client = clients.get(url)
+
+  if (!client) {
+    client = new Redis(url, { enableAutoPipelining: true })
+    clients.set(url, client)
+
+    globalThis.platformatic.events.on('plt:next:close', () => {
+      client.disconnect(false)
+    })
+  }
+
+  return client
+}
+
+export class CacheHandler {
+  #standalone
+  #config
+  #logger
+  #store
+  #prefix
+  #subprefix
+  #meta
+  #maxTTL
+  #cacheHitMetric
+  #cacheMissMetric
+
+  constructor (options) {
+    options ??= {}
+
+    this.#standalone = options.standalone
+    this.#config = options.config
+    this.#logger = options.logger
+    this.#store = options.store
+    this.#maxTTL = options.maxTTL
+    this.#prefix = options.prefix
+    this.#subprefix = options.subprefix
+    this.#meta = options.meta
+
+    if (!this.#standalone && globalThis.platformatic) {
+      this.#config ??= globalThis.platformatic.config.cache
+      this.#logger ??= this.#createPlatformaticLogger()
+      this.#store ??= getConnection(this.#config.url)
+      this.#maxTTL ??= this.#config.maxTTL
+      this.#prefix ??= this.#config.prefix
+      this.#subprefix ??= this.#getPlatformaticSubprefix()
+      this.#meta ??= this.#getPlatformaticMeta()
+    } else {
+      this.#config ??= {}
+      this.#maxTTL ??= 86_400
+      this.#prefix ??= ''
+      this.#subprefix ??= ''
+      this.#meta ??= {}
+    }
+
+    if (!this.#config) {
+      throw new Error('Please provide a the "config" option.')
+    }
+
+    if (!this.#logger) {
+      throw new Error('Please provide a the "logger" option.')
+    }
+
+    if (!this.#store) {
+      throw new Error('Please provide a the "store" option.')
+    }
+
+    if (globalThis.platformatic) {
+      this.#registerMetrics()
+    }
+  }
+
+  async get (cacheKey, _, isRedisKey) {
+    this.#logger.trace({ key: cacheKey }, 'cache get')
+
+    const key = this.#standalone || isRedisKey ? cacheKey : this.#keyFor(cacheKey, sections.values)
+
+    let rawValue
+    try {
+      rawValue = await this.#store.get(key)
+
+      if (!rawValue) {
+        this.#cacheMissMetric?.inc()
+        return
+      }
+    } catch (e) {
+      this.#cacheMissMetric?.inc()
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot read cache value from Valkey')
+      throw new Error('Cannot read cache value from Valkey', { cause: e })
+    }
+
+    let value
+    try {
+      value = this.#deserialize(rawValue)
+    } catch (e) {
+      this.#cacheMissMetric?.inc()
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot deserialize cache value from Valkey')
+
+      // Avoid useless reads the next time
+      // Note that since the value was unserializable, we don't know its tags and thus
+      // we cannot remove it from the tags sets. TTL will take care of them.
+      await this.#store.del(key)
+
+      throw new Error('Cannot deserialize cache value from Valkey', { cause: e })
+    }
+
+    if (this.#maxTTL < value.revalidate) {
+      try {
+        await this.#refreshKey(key, value)
+      } catch (e) {
+        this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot refresh cache key expiration in Valkey')
+
+        // We don't throw here since we want to use the cached value anyway
+      }
+    }
+
+    this.#cacheHitMetric?.inc()
+    return value
+  }
+
+  async set (cacheKey, value, ctx, isRedisKey) {
+    const tags = ctx.tags
+    const revalidate = ctx.revalidate ?? ctx.cacheControl?.revalidate ?? value.revalidate ?? 0
+
+    this.#logger.trace({ key: cacheKey, value, tags, revalidate }, 'cache set')
+
+    const key = this.#standalone || isRedisKey ? cacheKey : this.#keyFor(cacheKey, sections.values)
+
+    try {
+      // Compute the parameters to save
+      const data = this.#serialize({
+        value,
+        tags,
+        lastModified: Date.now(),
+        revalidate,
+        maxTTL: this.#maxTTL,
+        ...this.#meta
+      })
+      const expire = Math.min(revalidate, this.#maxTTL)
+
+      if (expire < 1) {
+        return
+      }
+
+      // Enqueue all the operations to perform in Valkey
+
+      const promises = []
+      promises.push(this.#store.set(key, data, 'EX', expire))
+
+      // As Next.js limits tags to 64, we don't need to manage batches here
+      if (Array.isArray(tags)) {
+        for (const tag of tags) {
+          const tagsKey = this.#keyFor(tag, sections.tags)
+          promises.push(this.#store.sadd(tagsKey, key))
+          promises.push(this.#store.expire(tagsKey, expire))
+        }
+      }
+
+      // Execute all the operations
+      await Promise.all(promises)
+    } catch (e) {
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot write cache value in Valkey')
+      throw new Error('Cannot write cache value in Valkey', { cause: e })
+    }
+  }
+
+  async remove (cacheKey, isRedisKey) {
+    this.#logger.trace({ key: cacheKey }, 'cache remove')
+
+    const key = this.#standalone || isRedisKey ? cacheKey : this.#keyFor(cacheKey, sections.values)
+
+    let rawValue
+    try {
+      rawValue = await this.#store.get(key)
+
+      if (!rawValue) {
+        return
+      }
+    } catch (e) {
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot read cache value from Valkey')
+      throw new Error('Cannot read cache value from Valkey', { cause: e })
+    }
+
+    let value
+    try {
+      value = this.#deserialize(rawValue)
+    } catch (e) {
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot deserialize cache value from Valkey')
+
+      // Avoid useless reads the next time
+      // Note that since the value was unserializable, we don't know its tags and thus
+      // we cannot remove it from the tags sets. TTL will take care of them.
+      await this.#store.del(key)
+
+      throw new Error('Cannot deserialize cache value from Valkey', { cause: e })
+    }
+
+    try {
+      const promises = []
+      promises.push(this.#store.del(key))
+
+      if (Array.isArray(value.tags)) {
+        for (const tag of value.tags) {
+          const tagsKey = this.#keyFor(tag, sections.tags)
+          promises.push(this.#store.srem(tagsKey, key))
+        }
+      }
+
+      // Execute all the operations
+      await Promise.all(promises)
+    } catch (e) {
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot remove cache value from Valkey')
+      throw new Error('Cannot remove cache value from Valkey', { cause: e })
+    }
+  }
+
+  async revalidateTag (tags) {
+    this.#logger.trace({ tags }, 'cache revalidateTag')
+
+    if (typeof tags === 'string') {
+      tags = [tags]
+    }
+
+    try {
+      let promises = []
+
+      for (const tag of tags) {
+        const tagsKey = this.#keyFor(tag, sections.tags)
+
+        // For each key in the tag set, expire the key
+        for await (const keys of this.#store.sscanStream(tagsKey)) {
+          for (const key of keys) {
+            promises.push(this.#store.del(key))
+
+            // Batch full, execute it
+            if (promises.length >= MAX_BATCH_SIZE) {
+              await Promise.all(promises)
+              promises = []
+            }
+          }
+        }
+
+        // Delete the set, this will also take care of executing pending operation for a non full batch
+        promises.push(this.#store.del(tagsKey))
+        await Promise.all(promises)
+        promises = []
+      }
+    } catch (e) {
+      this.#logger.error({ err: ensureLoggableError(e) }, 'Cannot expire cache tags in Valkey')
+      throw new Error('Cannot expire cache tags in Valkey', { cause: e })
+    }
+  }
+
+  async #refreshKey (key, value) {
+    const life = Math.round((Date.now() - value.lastModified) / 1000)
+    const expire = Math.min(value.revalidate - life, this.#maxTTL)
+
+    if (expire < 1) {
+      return
+    }
+
+    const promises = []
+    promises.push(this.#store.expire(key, expire, 'gt'))
+
+    if (Array.isArray(value.tags)) {
+      for (const tag of value.tags) {
+        const tagsKey = this.#keyFor(tag, sections.tags)
+        promises.push(this.#store.expire(tagsKey, expire, 'gt'))
+      }
+    }
+
+    await Promise.all(promises)
+  }
+
+  #createPlatformaticLogger () {
+    const loggerConfig = globalThis.platformatic?.config?.logger
+
+    const pinoOptions = {
+      ...loggerConfig,
+      level: globalThis.platformatic?.logLevel ?? loggerConfig?.level ?? 'info'
+    }
+    if (pinoOptions.formatters) {
+      pinoOptions.formatters = buildPinoFormatters(pinoOptions.formatters)
+    }
+    if (pinoOptions.timestamp) {
+      pinoOptions.timestamp = buildPinoTimestamp(pinoOptions.timestamp)
+    }
+
+    if (this.applicationId) {
+      pinoOptions.name = `cache:${this.applicationId}`
+    }
+
+    if (pinoOptions.base !== null && typeof globalThis.platformatic.workerId !== 'undefined') {
+      pinoOptions.base = {
+        ...(pinoOptions.base ?? {}),
+        pid: process.pid,
+        hostname: hostname(),
+        worker: this.workerId
+      }
+    } else if (pinoOptions.base === null) {
+      pinoOptions.base = undefined
+    }
+
+    return pino(pinoOptions)
+  }
+
+  #getPlatformaticSubprefix () {
+    const root = fileURLToPath(globalThis.platformatic.root)
+
+    return existsSync(resolve(root, '.next/BUILD_ID'))
+      ? (this.#subprefix = readFileSync(resolve(root, '.next/BUILD_ID'), 'utf-8').trim())
+      : 'development'
+  }
+
+  #getPlatformaticMeta () {
+    return {
+      applicationId: globalThis.platformatic.applicationId,
+      workerId: globalThis.platformatic.workerId
+    }
+  }
+
+  #keyFor (key, section) {
+    return keyFor(this.#prefix, this.#subprefix, section, key)
+  }
+
+  #serialize (data) {
+    return pack(data).toString('base64url')
+  }
+
+  #deserialize (data) {
+    return unpack(Buffer.from(data, 'base64url'))
+  }
+
+  #registerMetrics () {
+    const { client, registry } = globalThis.platformatic.prometheus
+
+    this.#cacheHitMetric =
+      registry.getSingleMetric(CACHE_HIT_METRIC.name) ??
+      new client.Counter({
+        name: CACHE_HIT_METRIC.name,
+        help: CACHE_HIT_METRIC.help,
+        registers: [registry]
+      })
+
+    this.#cacheMissMetric =
+      registry.getSingleMetric(CACHE_MISS_METRIC.name) ??
+      new client.Counter({
+        name: CACHE_MISS_METRIC.name,
+        help: CACHE_MISS_METRIC.help,
+        registers: [registry]
+      })
+  }
+}
+
+export default CacheHandler

package/lib/capability.js

@@ -0,0 +1,339 @@
+import {
+  BaseCapability,
+  ChildManager,
+  cleanBasePath,
+  createChildProcessListener,
+  createServerListener,
+  errors,
+  getServerUrl,
+  importFile,
+  resolvePackage
+} from '@platformatic/basic'
+import { ChildProcess } from 'node:child_process'
+import { once } from 'node:events'
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parse, satisfies } from 'semver'
+import { version } from './schema.js'
+
+const supportedVersions = ['^14.0.0', '^15.0.0']
+
+export class NextCapability extends BaseCapability {
+  #basePath
+  #next
+  #nextVersion
+  #child
+  #server
+
+  constructor (root, config, context) {
+    super('next', version, root, config, context)
+  }
+
+  async init () {
+    await super.init()
+
+    // This is needed to avoid Next.js to throw an error when the lockfile is not correct
+    // and the user is using npm but has pnpm in its $PATH.
+    //
+    // See: https://github.com/platformatic/composer-next-node-fastify/pull/3
+    //
+    // PS by Paolo: Sob.
+    process.env.NEXT_IGNORE_INCORRECT_LOCKFILE = 'true'
+
+    this.#next = resolvePath(dirname(resolvePackage(this.root, 'next')), '../..')
+    const nextPackage = JSON.parse(await readFile(resolvePath(this.#next, 'package.json'), 'utf-8'))
+    this.#nextVersion = parse(nextPackage.version)
+
+    if (this.#nextVersion.major < 15 || (this.#nextVersion.major <= 15 && this.#nextVersion.minor < 1)) {
+      await import('./create-context-patch.js')
+    }
+
+    /* c8 ignore next 3 */
+    if (!supportedVersions.some(v => satisfies(nextPackage.version, v))) {
+      throw new errors.UnsupportedVersion('next', nextPackage.version, supportedVersions)
+    }
+  }
+
+  async start ({ listen }) {
+    // Make this idempotent
+    if (this.url) {
+      return this.url
+    }
+
+    this.on('config', config => {
+      this.#basePath = config.basePath
+    })
+
+    if (this.isProduction) {
+      await this.#startProduction(listen)
+    } else {
+      await this.#startDevelopment(listen)
+    }
+
+    await this._collectMetrics()
+  }
+
+  async stop () {
+    await super.stop()
+
+    if (this.subprocess) {
+      return this.stopCommand()
+    }
+
+    globalThis.platformatic.events.emit('plt:next:close')
+
+    if (this.isProduction && this.#server) {
+      await new Promise((resolve, reject) => {
+        this.#server.close(error => {
+          /* c8 ignore next 3 */
+          if (error) {
+            return reject(error)
+          }
+
+          resolve()
+        })
+      })
+
+      await this.childManager.close()
+    } else if (this.#child) {
+      const exitPromise = once(this.#child, 'exit')
+      await this.childManager.close()
+      process.kill(this.#child.pid, 'SIGKILL')
+      await exitPromise
+    }
+  }
+
+  async build () {
+    if (!this.#nextVersion) {
+      await this.init()
+    }
+
+    const config = this.config
+    const loader = new URL('./loader.js', import.meta.url)
+    this.#basePath = config.application?.basePath ? cleanBasePath(config.application?.basePath) : ''
+
+    let command = config.application.commands.build
+
+    if (!command) {
+      await this.init()
+      command = ['node', resolvePath(this.#next, './dist/bin/next'), 'build', this.root]
+    }
+
+    await this.buildWithCommand(command, this.#basePath, { loader, scripts: this.#getChildManagerScripts() })
+
+    // This is need to avoid Next.js 15.4+ to throw an error as process.cwd() is not the root of the Next.js application
+    if (
+      config.cache?.adapter &&
+      (this.#nextVersion.major > 15 || (this.#nextVersion.major === 15 && this.#nextVersion.minor >= 4))
+    ) {
+      const distDir = resolvePath(this.root, '.next')
+      const requiredServerFilesPath = resolvePath(distDir, 'required-server-files.json')
+      const requiredServerFiles = JSON.parse(await readFile(requiredServerFilesPath, 'utf-8'))
+
+      if (requiredServerFiles.config.cacheHandler) {
+        requiredServerFiles.config.cacheHandler = resolvePath(distDir, requiredServerFiles.config.cacheHandler)
+        await writeFile(requiredServerFilesPath, JSON.stringify(requiredServerFiles, null, 2))
+      }
+    }
+  }
+
+  /* c8 ignore next 5 */
+  async getWatchConfig () {
+    return {
+      enabled: false,
+      path: this.root
+    }
+  }
+
+  getMeta () {
+    const gateway = { prefix: this.basePath ?? this.#basePath, wantsAbsoluteUrls: true, needsRootTrailingSlash: false }
+
+    if (this.url) {
+      gateway.tcp = true
+      gateway.url = this.url
+    }
+
+    return { gateway }
+  }
+
+  async getChildManagerContext (basePath) {
+    const context = await super.getChildManagerContext(basePath)
+
+    context.exitOnUnhandledErrors = false
+
+    return context
+  }
+
+  async #startDevelopment () {
+    const config = this.config
+    const loaderUrl = new URL('./loader.js', import.meta.url)
+    const command = this.config.application.commands.development
+
+    this.#basePath = config.application?.basePath ? cleanBasePath(config.application?.basePath) : ''
+
+    if (command) {
+      return this.startWithCommand(command, loaderUrl, this.#getChildManagerScripts())
+    }
+
+    const { hostname, port } = this.serverConfig ?? {}
+    const serverOptions = {
+      host: hostname || '127.0.0.1',
+      port: port || 0
+    }
+
+    const context = await this.getChildManagerContext(this.#basePath)
+
+    this.childManager = new ChildManager({
+      loader: loaderUrl,
+      context: {
+        ...context,
+        port: false,
+        wantsAbsoluteUrls: true
+      },
+      scripts: this.#getChildManagerScripts()
+    })
+
+    const promise = once(this.childManager, 'url')
+    await this.#startDevelopmentNext(serverOptions)
+    const [url, clientWs] = await promise
+    this.url = url
+    this.clientWs = clientWs
+  }
+
+  async #startDevelopmentNext (serverOptions) {
+    const { nextDev } = await importFile(resolvePath(this.#next, './dist/cli/next-dev.js'))
+
+    try {
+      await this.childManager.inject()
+      const childPromise = createChildProcessListener()
+
+      this.#ensurePipeableStreamsInFork()
+
+      if (this.#nextVersion.major === 14 && this.#nextVersion.minor < 2) {
+        await nextDev({
+          '--hostname': serverOptions.host,
+          '--port': serverOptions.port,
+          _: [this.root]
+        })
+      } else {
+        await nextDev(serverOptions, 'default', this.root)
+      }
+
+      this.#child = await childPromise
+      this.#child.stdout.setEncoding('utf8')
+      this.#child.stderr.setEncoding('utf8')
+
+      this.#child.stdout.pipe(process.stdout, { end: false })
+      this.#child.stderr.pipe(process.stderr, { end: false })
+    } finally {
+      await this.childManager.eject()
+    }
+  }
+
+  async #startProduction (listen) {
+    const config = this.config
+    const loaderUrl = new URL('./loader.js', import.meta.url)
+    const command = this.config.application.commands.production
+
+    this.#basePath = config.application?.basePath ? cleanBasePath(config.application?.basePath) : ''
+
+    if (command) {
+      const childManagerScripts = this.#getChildManagerScripts()
+
+      if (this.#nextVersion.major < 15 || (this.#nextVersion.major <= 15 && this.#nextVersion.minor < 1)) {
+        childManagerScripts.push(new URL('./create-context-patch.js', import.meta.url))
+      }
+      return this.startWithCommand(command, loaderUrl, childManagerScripts)
+    }
+
+    this.childManager = new ChildManager({
+      loader: loaderUrl,
+      context: {
+        config: this.config,
+        applicationId: this.applicationId,
+        workerId: this.workerId,
+        // Always use URL to avoid serialization problem in Windows
+        root: pathToFileURL(this.root).toString(),
+        basePath: this.#basePath,
+        logLevel: this.logger.level,
+        isEntrypoint: this.isEntrypoint,
+        runtimeBasePath: this.runtimeConfig.basePath,
+        wantsAbsoluteUrls: true,
+        telemetryConfig: this.telemetryConfig
+      },
+      scripts: this.#getChildManagerScripts()
+    })
+
+    this.verifyOutputDirectory(resolvePath(this.root, '.next'))
+    await this.#startProductionNext()
+  }
+
+  async #startProductionNext () {
+    try {
+      globalThis.platformatic.config = this.config
+      await this.childManager.inject()
+      const { nextStart } = await importFile(resolvePath(this.#next, './dist/cli/next-start.js'))
+
+      const { hostname, port } = this.serverConfig ?? {}
+      const serverOptions = {
+        hostname: hostname || '127.0.0.1',
+        port: port || 0
+      }
+
+      this.childManager.register()
+      const serverPromise = createServerListener(
+        (this.isEntrypoint ? serverOptions?.port : undefined) ?? true,
+        (this.isEntrypoint ? serverOptions?.hostname : undefined) ?? true
+      )
+
+      if (this.#nextVersion.major === 14 && this.#nextVersion.minor < 2) {
+        await nextStart({
+          '--hostname': serverOptions.host,
+          '--port': serverOptions.port,
+          _: [this.root]
+        })
+      } else {
+        await nextStart(serverOptions, this.root)
+      }
+
+      this.#server = await serverPromise
+      this.url = getServerUrl(this.#server)
+    } finally {
+      await this.childManager.eject()
+    }
+  }
+
+  #getChildManagerScripts () {
+    const scripts = []
+
+    if (this.#nextVersion.major === 15) {
+      scripts.push(new URL('./loader-next-15.cjs', import.meta.url))
+    }
+
+    return scripts
+  }
+
+  // In development mode, Next.js starts the dev server using child_process.fork with stdio set to 'inherit'.
+  // In order to capture the output, we need to ensure that the streams are pipeable and thus we perform a one-time
+  // monkey-patch of the ChildProcess.prototype.spawn method to override stdio[1] and stdio[2] to 'pipe'.
+  #ensurePipeableStreamsInFork () {
+    const originalSpawn = ChildProcess.prototype.spawn
+
+    // IMPORTANT: If Next.js code changes this might not work anymore. When this gives error, dig into Next.js code
+    // to evaluate the new path and/or if this is still necessary.
+    const startServerPath = resolvePath(this.#next, './dist/server/lib/start-server.js')
+
+    ChildProcess.prototype.spawn = function (options) {
+      if (options.args?.[1] === startServerPath) {
+        options.stdio[1] = 'pipe'
+        options.stdio[2] = 'pipe'
+
+        // Uninstall the patch
+        ChildProcess.prototype.spawn = originalSpawn
+      }
+
+      return originalSpawn.call(this, options)
+    }
+  }
+}