@platformatic/service 1.13.7 → 1.14.0

package/help/help.txt

@@ -1,6 +1,9 @@
 Available commands:
 
 * `help` - show this help message.
-* `help <command>` - shows more information about a command.
+* `help <command>` - show more information about a command.
 * `start` - start the server.
 * `schema config` - generate the schema configuration file.
+* `compile` - compile the typescript files.
+* `versions bump` - bump a new version of the API.
+* `versions update` - update the latest version of the API.

package/help/versions bump.txt

@@ -0,0 +1,25 @@
+Bump a new version of platformatic application API.
+
+``` bash
+  $ platformatic service versions bump
+```
+
+As a result, a new application API version will be created, and mappers for the previous version will be generated.
+
+Options:
+
+* `-c, --config <path>` - Path to the configuration file.
+* `-v, --version <string>` - The name of the version to bump. Default: if first version, then `v1`, else `vX`.
+* `-p, --prefix <string>` - The prefix to use for the new version. Default: if first version, then `/v1`, else `/vX`.
+* `--openai` - Use OpenAI to generate the version mappers plugins. Default: false.
+* `--user-api-key <string>` - Platformatic user API key. If not specified, the key will be loaded from the `~/.platformatic/config` file.
+
+If not specified, the configuration will be loaded from any of the following, in the current directory.
+
+* `platformatic.db.json`, or
+* `platformatic.db.yml`, or 
+* `platformatic.db.tml`
+
+You can find more details about the configuration format here:
+* [Platformatic DB Configuration](https://docs.platformatic.dev/docs/reference/db/configuration)
+

package/help/versions update.txt

@@ -0,0 +1,23 @@
+Update the latest version of platformatic application API.
+
+``` bash
+  $ platformatic service versions update
+```
+
+As a result, the latest application API version will be updated, and mappers for the previous version will be generated.
+
+Options:
+
+* `-c, --config <path>` - Path to the configuration file.
+* `--openai <boolean>` - Use OpenAI to generate the version mappers plugins. Default: false.
+* `--user-api-key <string>` - Platformatic user API key. If not specified, the key will be loaded from the `~/.platformatic/config` file.
+
+If not specified, the configuration will be loaded from any of the following, in the current directory.
+
+* `platformatic.db.json`, or
+* `platformatic.db.yml`, or 
+* `platformatic.db.tml`
+
+You can find more details about the configuration format here:
+* [Platformatic DB Configuration](https://docs.platformatic.dev/docs/reference/db/configuration)
+

package/index.js

@@ -13,6 +13,7 @@ const setupMetrics = require('./lib/plugins/metrics')
 const setupTsCompiler = require('./lib/plugins/typescript')
 const setupHealthCheck = require('./lib/plugins/health-check')
 const loadPlugins = require('./lib/plugins/plugins')
+const loadVersions = require('./lib/plugins/versions')
 const { telemetry } = require('@platformatic/telemetry')
 
 const { schema } = require('./lib/schema')
@@ -45,17 +46,15 @@ async function platformaticService (app, opts, toLoad) {
   const serviceConfig = config.service || {}
 
   if (isKeyEnabled('openapi', serviceConfig)) {
-    app.register(setupOpenAPI, serviceConfig.openapi)
+    const openapi = serviceConfig.openapi
+    const versions = config.versions
+    app.register(setupOpenAPI, { openapi, versions })
   }
 
   if (isKeyEnabled('graphql', serviceConfig)) {
     app.register(setupGraphQL, serviceConfig.graphql)
   }
 
-  if (isKeyEnabled('clients', config)) {
-    app.register(setupClients, config.clients)
-  }
-
   if (config.plugins) {
     let registerTsCompiler = false
     const typescript = config.plugins.paths && config.plugins.typescript
@@ -72,6 +71,17 @@ async function platformaticService (app, opts, toLoad) {
     app.register(loadPlugins)
   }
 
+  await app.register(async (app) => {
+    if (config.versions) {
+      // TODO: Add typescript mappers support
+      await app.register(loadVersions)
+    }
+  })
+
+  if (isKeyEnabled('clients', config)) {
+    app.register(setupClients, config.clients)
+  }
+
   if (isKeyEnabled('cors', config.server)) {
     app.register(setupCors, config.server.cors)
   }

package/lib/bump-version.js

@@ -0,0 +1,178 @@
+'use strict'
+
+const { join, relative } = require('node:path')
+const { mkdir, readFile, writeFile } = require('node:fs/promises')
+const pino = require('pino')
+const pretty = require('pino-pretty')
+const { loadConfig } = require('@platformatic/config')
+const { analyze, write: writeConfig } = require('@platformatic/metaconfig')
+const { platformaticService } = require('../index.js')
+const { getOpenapiSchema } = require('./get-openapi-schema.js')
+const { createMappersPlugins } = require('./update-version.js')
+const { changeOpenapiSchemaPrefix } = require('./utils')
+const errors = require('./errors.js')
+
+async function execute ({
+  logger,
+  configManager,
+  version,
+  prefix,
+  userApiKey,
+  openai,
+  openaiProxyHost
+}) {
+  const config = configManager.current
+
+  const metaConfig = await analyze({ file: configManager.fullPath })
+  const rawConfig = metaConfig.config
+
+  const versionsDirName = 'versions'
+  const versionsDirPath = config.versions?.dir ??
+    join(configManager.dirname, versionsDirName)
+
+  let versionsConfigs = config.versions
+  let rawVersionsConfigs = rawConfig.versions
+
+  if (!config.versions) {
+    versionsConfigs = { dir: versionsDirName, configs: [] }
+    rawVersionsConfigs = { dir: versionsDirName, configs: [] }
+  }
+
+  let biggestVersion = 0
+  for (const versionConfig of versionsConfigs.configs) {
+    if (versionConfig.version === version) {
+      throw new errors.VersionAlreadyExists(version)
+    }
+    const versionNumber = parseInt(versionConfig.version.slice(1))
+    if (!isNaN(versionNumber)) {
+      biggestVersion = Math.max(biggestVersion, versionNumber)
+    }
+  }
+  version = version ?? `v${biggestVersion + 1}`
+  prefix = prefix ?? `/${version}`
+  prefix = prefix.charAt(0) === '/' ? prefix : `/${prefix}`
+
+  const versionDir = join(versionsDirPath, version)
+  await mkdir(versionDir, { recursive: true })
+
+  const latestVersionConfig = versionsConfigs.configs.at(-1)
+  const rawLatestVersionConfig = rawVersionsConfigs.configs.at(-1)
+
+  const latestVersion = latestVersionConfig?.version ?? null
+  const latestVersionPrefix = latestVersionConfig?.openapi?.prefix ?? ''
+
+  logger.info('Loading the latest openapi schema.')
+  const latestOpenapiSchema = await getOpenapiSchema({
+    logger,
+    configManager,
+    version: latestVersion
+  })
+
+  const newOpenapiSchema = changeOpenapiSchemaPrefix(
+    latestOpenapiSchema,
+    latestVersionPrefix,
+    prefix
+  )
+  const newOpenapiSchemaPath = join(versionDir, 'openapi.json')
+
+  logger.info(`Writing "${version}" openapi schema file.`)
+  await writeFile(newOpenapiSchemaPath, JSON.stringify(newOpenapiSchema, null, 2))
+
+  const newVersionConfig = {
+    version,
+    openapi: {
+      path: relative(configManager.dirname, newOpenapiSchemaPath),
+      prefix
+    }
+  }
+
+  if (latestVersionConfig) {
+    newVersionConfig.plugins = rawLatestVersionConfig.plugins
+    delete latestVersionConfig.plugins
+    delete rawLatestVersionConfig.plugins
+  } else if (config.plugins) {
+    newVersionConfig.plugins = rawConfig.plugins
+    delete config.plugins
+    delete rawConfig.plugins
+  }
+
+  versionsConfigs.configs.push(newVersionConfig)
+  rawVersionsConfigs.configs.push(newVersionConfig)
+
+  config.versions = versionsConfigs
+  rawConfig.versions = rawVersionsConfigs
+
+  await Promise.all([configManager.update(), writeConfig(metaConfig)])
+
+  if (latestVersionConfig) {
+    logger.info(`Reading openapi schema for "${latestVersion}"`)
+    const prevOpenapiSchemaPath = latestVersionConfig.openapi.path
+    const prevOpenapiSchemaFile = await readFile(prevOpenapiSchemaPath, 'utf8')
+    const prevOpenapiSchema = JSON.parse(prevOpenapiSchemaFile)
+
+    await createMappersPlugins({
+      logger,
+      configManager,
+      prevVersion: latestVersion,
+      nextVersion: version,
+      prevOpenapiSchema,
+      nextOpenapiSchema: newOpenapiSchema,
+      userApiKey,
+      openai,
+      openaiProxyHost
+    })
+  }
+}
+
+async function bumpVersion (_args) {
+  const logger = pino(pretty({
+    translateTime: 'SYS:HH:MM:ss',
+    ignore: 'hostname,pid'
+  }))
+
+  try {
+    const { configManager, args } = await loadConfig({
+      string: ['version', 'prefix', 'openai-proxy-host', 'user-api-key'],
+      boolean: ['openai'],
+      alias: {
+        v: 'version',
+        p: 'prefix'
+      }
+    }, _args, platformaticService)
+    await configManager.parseAndValidate()
+
+    const version = args.version
+    const prefix = args.prefix
+
+    const openai = args.openai ?? false
+    const openaiProxyHost = args['openai-proxy-host'] ?? null
+
+    let userApiKey = args['user-api-key'] ?? null
+    /* c8 ignore next 10 */
+    if (!userApiKey && openai) {
+      logger.info('Reading platformatic user api key')
+      const { getUserApiKey } = await import('@platformatic/authenticate')
+      try {
+        userApiKey = await getUserApiKey()
+      } catch (err) {
+        logger.error('Failed to read user api key. Please run "plt login" command.')
+        return
+      }
+    }
+
+    await execute({
+      logger,
+      configManager,
+      version,
+      prefix,
+      userApiKey,
+      openai,
+      openaiProxyHost
+    })
+  } catch (err) {
+    logger.error(err.message)
+    process.exit(1)
+  }
+}
+
+module.exports = { bumpVersion, execute }

package/lib/errors.js

@@ -0,0 +1,16 @@
+'use strict'
+
+const createError = require('@fastify/error')
+
+const ERROR_PREFIX = 'PLT_SERVICE'
+
+module.exports = {
+  VersionNotSpecified: createError(
+    `${ERROR_PREFIX}_VERSION_NOT_SPECIFIED_ERROR`,
+    'Version not specified. Use --version option to specify a version.'
+  ),
+  VersionAlreadyExists: createError(
+    `${ERROR_PREFIX}_VERSION_EXISTS_ERROR`,
+    'Version %s already exists.'
+  )
+}

package/lib/get-openapi-schema.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const { printAndExitLoadConfigError } = require('@platformatic/config')
+const { buildServer } = require('./start')
+const { platformaticService } = require('../index.js')
+
+async function getOpenapiSchema ({ logger, configManager, version }) {
+  const config = configManager.current
+
+  let app = null
+  try {
+    app = await buildServer({ ...config, configManager }, platformaticService)
+    await app.ready()
+  /* c8 ignore next 4 */
+  } catch (err) {
+    printAndExitLoadConfigError(err)
+    process.exit(1)
+  }
+
+  if (!version) {
+    return app.swagger()
+  }
+
+  if (!config.versions) {
+    throw new Error('No versions configured')
+  }
+
+  const versionsConfigs = config.versions.configs ?? []
+  const versionConfig = versionsConfigs.find(v => v.version === version)
+  const versionPrefix = versionConfig.openapi.prefix ?? ''
+
+  const openapiUrl = versionPrefix
+    ? versionPrefix + '/documentation/json'
+    : '/documentation/json'
+
+  const { statusCode, body } = await app.inject({ method: 'GET', url: openapiUrl })
+
+  /* c8 ignore next 3 */
+  if (statusCode !== 200) {
+    throw new Error(`Failed to get openapi schema for version ${version}`)
+  }
+
+  const openapiSchema = JSON.parse(body)
+  return openapiSchema
+}
+
+module.exports = { getOpenapiSchema }

package/lib/plugins/openapi.js

@@ -10,6 +10,7 @@ const fp = require('fastify-plugin')
 // despite being covered by test/routes.test.js
 /* c8 ignore next 33 */
 async function setupOpenAPI (app, opts) {
+  const { openapi, versions } = opts
   const openapiConfig = deepmerge({
     exposeRoute: true,
     info: {
@@ -17,7 +18,7 @@ async function setupOpenAPI (app, opts) {
       description: 'This is a service built on top of Platformatic',
       version: '1.0.0'
     }
-  }, typeof opts === 'object' ? opts : {})
+  }, typeof openapi === 'object' ? openapi : {})
   app.log.trace({ openapi: openapiConfig })
   const swaggerOptions = {
     exposeRoute: openapiConfig.exposeRoute,
@@ -30,13 +31,24 @@ async function setupOpenAPI (app, opts) {
         /* istanbul ignore next */
         return json.$id || `def-${i}`
       }
+    },
+    transform: ({ schema, url }) => {
+      // Hide versioned endpoints
+      for (const version of versions?.configs ?? []) {
+        if (url.startsWith(version.openapi.prefix)) {
+          if (!schema) schema = {}
+          schema.hide = true
+          break
+        }
+      }
+      return { schema, url }
     }
   }
 
-  if (opts.path) {
+  if (openapi.path) {
     swaggerOptions.mode = 'static'
     swaggerOptions.specification = {
-      path: opts.path
+      path: openapi.path
     }
   }
   await app.register(Swagger, swaggerOptions)
@@ -44,7 +56,7 @@ async function setupOpenAPI (app, opts) {
   const { default: theme } = await import('@platformatic/swagger-ui-theme')
   app.register(SwaggerUI, {
     ...theme,
-    ...opts,
+    ...openapi,
     logLevel: 'warn',
     prefix: '/documentation'
   })

package/lib/plugins/versions.js

@@ -0,0 +1,211 @@
+'use strict'
+
+const { join } = require('node:path')
+const { readFile } = require('node:fs/promises')
+const deepClone = require('rfdc')({ proto: true })
+const compareOpenApiSchemas = require('openapi-schema-diff')
+const fp = require('fastify-plugin')
+const {
+  changeOpenapiSchemaPrefix,
+  convertOpenApiToFastifyPath
+} = require('../utils')
+
+const wrapperPath = join(__dirname, 'sandbox-wrapper.js')
+
+const Swagger = require('@fastify/swagger')
+const SwaggerUI = require('@fastify/swagger-ui')
+
+async function loadVersions (app) {
+  const configManager = app.platformatic.configManager
+  const config = configManager.current
+
+  const versions = config.versions ?? {}
+  const versionsConfigs = versions.configs ?? []
+
+  const latestVersionConfig = versionsConfigs.at(-1)
+  const latestVersion = latestVersionConfig.version
+  const latestVersionPrefix = latestVersionConfig.openapi.prefix ?? ''
+
+  const latestVersionPlugin = fp(async function (app) {
+    app.register(Swagger, {
+      exposeRoute: true,
+      openapi: {
+        info: {
+          title: 'Platformatic',
+          description: 'This is a service built on top of Platformatic',
+          version: latestVersion
+        }
+      },
+      refResolver: {
+        buildLocalReference (json, baseUri, fragment, i) {
+          /* istanbul ignore next */
+          return json.$id || `def-${i}`
+        }
+      }
+    })
+
+    app.register(SwaggerUI, {
+      logLevel: 'warn',
+      prefix: '/documentation'
+    })
+
+    if (latestVersionConfig.plugins) {
+      await app.register(require(wrapperPath), latestVersionConfig.plugins)
+    }
+  }, {
+    name: latestVersion,
+    encapsulate: true
+  })
+
+  await app.register(latestVersionPlugin, {
+    prefix: latestVersionPrefix
+  })
+
+  const latestOpenapiSchemaPath = latestVersionConfig.openapi.path
+  const latestOpenapiSchemaFile = await readFile(latestOpenapiSchemaPath, 'utf8')
+  const latestOpenapiSchema = JSON.parse(latestOpenapiSchemaFile)
+
+  let nextVersionPrefix = latestVersionPrefix
+  let nextNormalizedOpenapiSchema = changeOpenapiSchemaPrefix(
+    latestOpenapiSchema,
+    latestVersionConfig.openapi.prefix,
+    ''
+  )
+
+  for (let i = versionsConfigs.length - 2; i >= 0; i--) {
+    const prevVersionConfig = versionsConfigs[i]
+    const prevVersion = prevVersionConfig.version
+    const prevVersionPrefix = prevVersionConfig.openapi.prefix ?? ''
+    const prevOpenapiSchemaPath = prevVersionConfig.openapi.path
+
+    const prevOpenapiSchemaFile = await readFile(prevOpenapiSchemaPath, 'utf8')
+    const prevOpenapiSchema = JSON.parse(prevOpenapiSchemaFile)
+
+    const prevNormalizedOpenapiSchema = changeOpenapiSchemaPrefix(
+      prevOpenapiSchema,
+      prevVersionConfig.openapi.prefix,
+      ''
+    )
+
+    const schemaDiff = compareOpenApiSchemas(
+      prevNormalizedOpenapiSchema,
+      nextNormalizedOpenapiSchema
+    )
+
+    const versionPlugin = fp(async function (app) {
+      app.register(Swagger, {
+        exposeRoute: true,
+        openapi: {
+          info: {
+            title: 'Platformatic',
+            description: 'This is a service built on top of Platformatic',
+            version: prevVersion
+          }
+        },
+        refResolver: {
+          buildLocalReference (json, baseUri, fragment, i) {
+            /* istanbul ignore next */
+            return json.$id || `def-${i}`
+          }
+        }
+      })
+
+      app.register(SwaggerUI, {
+        logLevel: 'warn',
+        prefix: '/documentation'
+      })
+
+      const componentSchemas = prevOpenapiSchema.components?.schemas ?? {}
+      for (const componentSchemaId of Object.keys(componentSchemas)) {
+        const componentSchema = componentSchemas[componentSchemaId]
+        app.addSchema({ $id: componentSchemaId, ...componentSchema })
+      }
+
+      if (prevVersionConfig.plugins) {
+        await app.register(require(wrapperPath), prevVersionConfig.plugins)
+      }
+
+      for (const routeDiff of [...schemaDiff.deletedRoutes, ...schemaDiff.changedRoutes]) {
+        const method = routeDiff.method.toUpperCase()
+        const prevVersionPath = prevVersionPrefix + convertOpenApiToFastifyPath(routeDiff.path)
+
+        const hasRouteMapper = app.hasRoute({ url: prevVersionPath, method })
+        if (!hasRouteMapper) {
+          app.log.warn(`Missing route ${method} "${prevVersionPath}" in the "${prevVersion}" API version`)
+        }
+      }
+
+      const sameSchema = deepClone(prevNormalizedOpenapiSchema)
+      for (const normalizedPath in sameSchema.paths ?? {}) {
+        for (const method in sameSchema.paths[normalizedPath] ?? {}) {
+          const prevVersionPath = prevVersionPrefix + convertOpenApiToFastifyPath(normalizedPath)
+          const hasRouteMapper = app.hasRoute({
+            url: prevVersionPath,
+            method: method.toUpperCase()
+          })
+
+          const isSameRoute = schemaDiff.sameRoutes.find(
+            routeDiff =>
+              routeDiff.method === method.toLowerCase() &&
+              routeDiff.path === normalizedPath
+          )
+
+          if (!isSameRoute || hasRouteMapper) {
+            delete sameSchema.paths[normalizedPath][method]
+          }
+        }
+        if (Object.keys(sameSchema.paths[normalizedPath]).length === 0) {
+          delete sameSchema.paths[normalizedPath]
+        }
+      }
+
+      if (Object.keys(sameSchema.paths).length > 0) {
+        const versionPrefix = nextVersionPrefix
+
+        await app.register(await import('fastify-openapi-glue'), {
+          specification: sameSchema,
+          operationResolver: (operationId, method) => {
+            return {
+              handler: async (req, reply) => {
+                const prevVersionUrl = req.raw.url
+                const nextVersionUrl = prevVersionUrl.replace(
+                  prevVersionPrefix,
+                  versionPrefix
+                )
+
+                const headers = req.headers
+                delete headers.connection
+                delete headers['content-length']
+                delete headers['transfer-encoding']
+
+                const res = await app.inject({
+                  method: method.toUpperCase(),
+                  url: nextVersionUrl,
+                  headers,
+                  payload: req.body
+                })
+
+                reply
+                  .code(res.statusCode)
+                  .headers(res.headers)
+                  .send(res.body)
+              }
+            }
+          }
+        })
+      }
+    }, {
+      name: prevVersion,
+      encapsulate: true
+    })
+
+    await app.register(versionPlugin, {
+      prefix: prevVersionPrefix
+    })
+
+    nextVersionPrefix = prevVersionPrefix
+    nextNormalizedOpenapiSchema = prevNormalizedOpenapiSchema
+  }
+}
+
+module.exports = fp(loadVersions)

package/lib/root-endpoint/index.js

@@ -5,9 +5,27 @@ const fastifyStatic = require('@fastify/static')
 const userAgentParser = require('ua-parser-js')
 
 module.exports = async (app, opts) => {
+  const versions = opts.versions || {}
+
   app.register(fastifyStatic, {
     root: path.join(__dirname, 'public')
   })
+
+  app.route({
+    method: 'GET',
+    path: '/_platformatic_versions',
+    schema: { hide: true },
+    handler: () => {
+      const openapiUrls = []
+      for (const versionConfig of versions?.configs ?? []) {
+        const name = versionConfig.version
+        const prefix = versionConfig.openapi.prefix
+        openapiUrls.push({ name, prefix })
+      }
+      return openapiUrls
+    }
+  })
+
   // root endpoint
   app.route({
     method: 'GET',