@platformatic/gateway 3.0.0-alpha.6

package/eslint.config.js

@@ -0,0 +1,12 @@
+import neostandard from 'neostandard'
+
+export default neostandard({
+  ts: true,
+  ignores: [
+    ...neostandard.resolveIgnoresFromGitignore(),
+    'test/tmp/**/*',
+    'test/fixtures/*/dist/**/*',
+    '**/dist/*',
+    'tmp/**/*'
+  ]
+})

package/index.d.ts

@@ -0,0 +1,58 @@
+import { BaseCapability } from '@platformatic/basic'
+import { BaseGenerator } from '@platformatic/generators'
+import {
+  ApplicationCapability,
+  ServerInstance as ApplicationInstance,
+  Configuration,
+  ConfigurationOptions
+} from '@platformatic/service'
+import { JSONSchemaType } from 'ajv'
+import { FastifyError, FastifyInstance } from 'fastify'
+import { PlatformaticGatewayConfig } from './config'
+
+export { PlatformaticService } from '@platformatic/service'
+export { PlatformaticGatewayConfig } from './config'
+
+export type GatewayCapability = ApplicationCapability<PlatformaticGatewayConfig>
+
+export type ServerInstance = ApplicationInstance<PlatformaticGatewayConfig>
+
+type GatewayConfiguration = Configuration<PlatformaticGatewayConfig>
+
+export declare function loadConfiguration (
+  root: string | PlatformaticServiceConfig,
+  source?: string | PlatformaticServiceConfig,
+  context?: ConfigurationOptions
+): Promise<GatewayConfiguration>
+
+export function create (
+  root: string,
+  source?: string | PlatformaticGatewayConfig,
+  context?: ConfigurationOptions
+): Promise<GatewayCapability>
+
+export declare function platformaticGateway (app: FastifyInstance, capability: BaseCapability): Promise<void>
+
+export class Generator extends BaseGenerator.BaseGenerator {}
+
+export declare const packageJson: Record<string, unknown>
+
+export declare const schema: JSONSchemaType<PlatformaticGatewayConfig>
+
+export declare const schemaComponents: {
+  openApiApplication: JSONSchemaType<object>
+  entityResolver: JSONSchemaType<object>
+  entities: JSONSchemaType<object>
+  graphqlApplication: JSONSchemaType<object>
+  graphqlGatewayOptions: JSONSchemaType<object>
+  gateway: JSONSchemaType<object>
+  types: JSONSchemaType<object>
+}
+
+export declare const version: string
+
+export function FastifyInstanceIsAlreadyListeningError (): FastifyError
+export function FailedToFetchOpenAPISchemaError (): FastifyError
+export function ValidationErrors (): FastifyError
+export function PathAlreadyExistsError (): FastifyError
+export function CouldNotReadOpenAPIConfigError (): FastifyError

package/index.js

@@ -0,0 +1,34 @@
+import { resolve, validationOptions } from '@platformatic/basic'
+import { kMetadata, loadConfiguration as utilsLoadConfiguration } from '@platformatic/foundation'
+import { transform } from '@platformatic/service'
+import { GatewayCapability } from './lib/capability.js'
+import { schema } from './lib/schema.js'
+import { upgrade } from './lib/upgrade.js'
+
+export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
+  const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'gateway')
+
+  return utilsLoadConfiguration(source, context?.schema ?? schema, {
+    validationOptions,
+    transform,
+    upgrade,
+    replaceEnv: true,
+    root,
+    ...context
+  })
+}
+
+export async function create (configOrRoot, sourceOrConfig, context) {
+  const config = await loadConfiguration(configOrRoot, sourceOrConfig, context)
+  return new GatewayCapability(config[kMetadata].root, config, context)
+}
+
+export const skipTelemetryHooks = true
+
+export { platformaticGateway } from './lib/application.js'
+export { GatewayCapability } from './lib/capability.js'
+export * from './lib/commands/index.js'
+export * from './lib/errors.js'
+export * as errors from './lib/errors.js'
+export { Generator } from './lib/generator.js'
+export { packageJson, schema, schemaComponents, version } from './lib/schema.js'

package/lib/application.js

@@ -0,0 +1,186 @@
+import { isKeyEnabled } from '@platformatic/foundation'
+import { platformaticService } from '@platformatic/service'
+import deepEqual from 'fast-deep-equal'
+import { fetchOpenApiSchema } from './commands/openapi-fetch-schemas.js'
+import { gatewayHook } from './gateway-hook.js'
+import { fetchGraphqlSubgraphs, isSameGraphqlSchema } from './graphql-fetch.js'
+import { graphqlGenerator } from './graphql-generator.js'
+import { graphql } from './graphql.js'
+import { openApiGateway, openApiGenerator } from './openapi-generator.js'
+import { proxy } from './proxy.js'
+import { isFetchable } from './utils.js'
+
+const kITC = Symbol.for('plt.runtime.itc')
+const EXPERIMENTAL_GRAPHQL_GATEWAY_FEATURE_MESSAGE = 'graphql composer is an experimental feature'
+
+async function detectApplicationsUpdate ({ app, applications, fetchOpenApiSchema, fetchGraphqlSubgraphs }) {
+  let changed
+
+  const graphqlApplications = []
+  // assumes applications here are fetchable
+  for (const application of applications) {
+    const { id, origin, openapi, graphql } = application
+
+    if (openapi) {
+      const currentSchema = app.openApiSchemas.find(schema => schema.id === id)?.originSchema || null
+
+      let fetchedSchema = null
+      try {
+        fetchedSchema = await fetchOpenApiSchema({ origin, openapi })
+      } catch (err) {
+        app.log.error({ err }, 'failed to fetch schema (watch) for application ' + id)
+      }
+
+      if (!changed && !deepEqual(fetchedSchema, currentSchema)) {
+        changed = true
+        // it stops at first schema difference since all the schemas will be updated on reload
+        break
+      }
+    }
+
+    if (graphql) {
+      graphqlApplications.push(application)
+    }
+  }
+
+  if (!changed && graphqlApplications.length > 0) {
+    const graphqlSupergraph = await fetchGraphqlSubgraphs(graphqlApplications, app.graphqlGatewayOptions, app)
+    if (!isSameGraphqlSchema(graphqlSupergraph, app.graphqlSupergraph)) {
+      changed = true
+      app.graphqlSupergraph = graphqlSupergraph
+    }
+  }
+
+  return changed
+}
+
+/**
+ * poll applications to detect changes, every `opts.gateway.refreshTimeout`
+ * polling is disabled on refreshTimeout = 0
+ * or there are no network openapi nor graphql remote applications (the applications are from file or they don't have a schema/graph to fetch)
+ */
+async function watchApplications (app, { config, capability }) {
+  const { applications, refreshTimeout } = config.gateway
+  if (refreshTimeout < 1) {
+    return
+  }
+
+  const watching = applications.filter(isFetchable)
+  if (watching.length < 1) {
+    return
+  }
+
+  if (!globalThis[Symbol.for('plt.runtime.id')]) {
+    app.log.warn('Watching applications is only supported when running within a Platformatic Runtime.')
+    return
+  }
+
+  capability.emit('watch:start')
+  app.log.info({ applications: watching }, 'start watching applications')
+
+  const timer = setInterval(async () => {
+    try {
+      if (await detectApplicationsUpdate({ app, applications: watching, fetchOpenApiSchema, fetchGraphqlSubgraphs })) {
+        clearInterval(timer)
+        app.log.info('detected applications changes, restarting ...')
+
+        globalThis[Symbol.for('plt.runtime.itc')].notify('changed')
+      }
+    } catch (error) {
+      app.log.error(
+        {
+          err: {
+            message: error.message,
+            stack: error.stack
+          }
+        },
+        'failed to get applications info'
+      )
+    }
+  }, refreshTimeout).unref()
+
+  app.addHook('onClose', async () => {
+    clearInterval(timer)
+  })
+}
+
+export async function ensureApplications (gatewayId, config) {
+  if (config.gateway?.applications?.length) {
+    return
+  }
+
+  gatewayId ??= globalThis.platformatic?.applicationId
+  config.gateway ??= {}
+  config.gateway.applications ??= []
+
+  // When no applications are defined, all applications are exposed in the gateway
+  const applications = await globalThis[kITC]?.send('listApplications')
+
+  if (applications) {
+    config.gateway.applications = applications
+      .filter(id => id !== gatewayId) // Remove ourself
+      .map(id => ({ id, proxy: { prefix: `/${id}` } }))
+  }
+}
+
+export async function platformaticGateway (app, capability) {
+  const config = await capability.getConfig()
+  let hasGraphqlApplications, hasOpenapiApplications
+
+  // When no applications are specified, get the list from the runtime.
+  await ensureApplications(capability.applicationId, config)
+
+  const { applications } = config.gateway
+
+  for (const application of applications) {
+    if (!application.origin) {
+      application.origin = `http://${application.id}.plt.local`
+    }
+    if (application.openapi && !hasOpenapiApplications) {
+      hasOpenapiApplications = true
+    }
+    if (application.graphql && !hasGraphqlApplications) {
+      hasGraphqlApplications = true
+    }
+  }
+
+  await app.register(gatewayHook)
+
+  let generatedComposedOpenAPI = null
+  if (hasOpenapiApplications) {
+    generatedComposedOpenAPI = await openApiGenerator(app, config.gateway)
+  }
+
+  if (isKeyEnabled('healthCheck', config.server)) {
+    if (typeof config.server.healthCheck !== 'object') {
+      config.server.healthCheck = {}
+    }
+
+    config.server.healthCheck.fn = capability.isHealthy.bind(capability)
+  }
+
+  await app.register(proxy, { ...config.gateway, capability, context: capability.context })
+
+  await platformaticService(app, capability)
+
+  if (generatedComposedOpenAPI) {
+    await app.register(openApiGateway, { opts: config.gateway, generated: generatedComposedOpenAPI })
+  }
+
+  if (hasGraphqlApplications) {
+    app.log.warn(EXPERIMENTAL_GRAPHQL_GATEWAY_FEATURE_MESSAGE)
+    app.register(graphql, config.gateway)
+    await app.register(graphqlGenerator, config.gateway)
+  }
+
+  if (!app.hasRoute({ url: '/', method: 'GET' }) && !app.hasRoute({ url: '/*', method: 'GET' })) {
+    const rootHandler = await import('./root.js')
+    await app.register(rootHandler.default, config)
+  }
+
+  if (!capability.context?.isProduction) {
+    await watchApplications(app, { config, capability, context: capability.context })
+  }
+}
+
+platformaticGateway[Symbol.for('skip-override')] = true

package/lib/capability.js

@@ -0,0 +1,89 @@
+import { kMetadata, replaceEnv } from '@platformatic/foundation'
+import { ServiceCapability } from '@platformatic/service'
+import { ensureApplications, platformaticGateway } from './application.js'
+import { notHostConstraints } from './not-host-constraints.js'
+import { packageJson } from './schema.js'
+
+const kITC = Symbol.for('plt.runtime.itc')
+
+export class GatewayCapability extends ServiceCapability {
+  #meta
+  #dependencies
+
+  constructor (root, config, context) {
+    super(root, config, context)
+    this.type = 'gateway'
+    this.version = packageJson.version
+
+    this.applicationFactory = this.context.applicationFactory ?? platformaticGateway
+    this.fastifyOptions ??= {}
+    this.fastifyOptions.routerOptions ??= {}
+    this.fastifyOptions.routerOptions.constraints = { notHost: notHostConstraints }
+  }
+
+  async getBootstrapDependencies () {
+    await ensureApplications(this.applicationId, this.config)
+
+    const composedApplications = this.config.gateway?.applications
+    const dependencies = []
+
+    if (Array.isArray(composedApplications)) {
+      dependencies.push(
+        ...(await Promise.all(
+          composedApplications.map(async application => {
+            return this.#parseDependency(application.id, application.origin)
+          })
+        ))
+      )
+    }
+
+    this.#dependencies = dependencies
+    return this.#dependencies
+  }
+
+  registerMeta (meta) {
+    this.#meta = Object.assign(this.#meta ?? {}, meta)
+  }
+
+  async getMeta () {
+    const applicationMeta = super.getMeta()
+    const gatewayMeta = this.#meta ? { gateway: this.#meta } : undefined
+
+    return {
+      ...applicationMeta,
+      ...gatewayMeta
+    }
+  }
+
+  async isHealthy () {
+    // If no dependencies (still booting), assume healthy
+    if (this.#dependencies) {
+      const composedApplications = this.#dependencies.map(dep => dep.id)
+      const workers = await globalThis[kITC].send('getWorkers')
+
+      for (const worker of Object.values(workers)) {
+        if (composedApplications.includes(worker.application) && !worker.status.startsWith('start')) {
+          globalThis[kITC].notify('event', { event: 'unhealthy' })
+          return false
+        }
+      }
+    }
+
+    globalThis[kITC].notify('event', { event: 'healthy' })
+    return true
+  }
+
+  async #parseDependency (id, urlString) {
+    let url = `http://${id}.plt.local`
+
+    if (urlString) {
+      const remoteUrl = await replaceEnv(urlString, this.config[kMetadata].env)
+
+      if (remoteUrl) {
+        url = remoteUrl
+      }
+    }
+
+    return { id, url, local: url.endsWith('.plt.local') }
+  }
+}

package/lib/commands/index.js

@@ -0,0 +1,15 @@
+import { fetchOpenApiSchemas } from './openapi-fetch-schemas.js'
+
+export function createCommands (id) {
+  return {
+    commands: {
+      [`${id}:fetch-openapi-schemas`]: fetchOpenApiSchemas
+    },
+    help: {
+      [`${id}:fetch-openapi-schemas`]: {
+        usage: `${id}:fetch-openapi-schemas`,
+        description: 'Fetch OpenAPI schemas from remote applications'
+      }
+    }
+  }
+}

package/lib/commands/openapi-fetch-schemas.js

@@ -0,0 +1,48 @@
+import { loadConfiguration } from '@platformatic/foundation'
+import { writeFile } from 'node:fs/promises'
+import { request } from 'undici'
+import { FailedToFetchOpenAPISchemaError } from '../errors.js'
+import { schema } from '../schema.js'
+import { upgrade } from '../upgrade.js'
+import { prefixWithSlash } from '../utils.js'
+
+export async function fetchOpenApiSchema (application) {
+  const { origin, openapi } = application
+
+  const openApiUrl = origin + prefixWithSlash(openapi.url)
+  const { statusCode, body } = await request(openApiUrl)
+
+  if (statusCode !== 200 && statusCode !== 201) {
+    throw new FailedToFetchOpenAPISchemaError(openApiUrl)
+  }
+  const schema = await body.json()
+
+  if (openapi.file !== undefined) {
+    await writeFile(openapi.file, JSON.stringify(schema, null, 2))
+  }
+
+  return schema
+}
+
+export async function fetchOpenApiSchemas (logger, configFile, _args, { colorette }) {
+  const { bold } = colorette
+  const config = await loadConfiguration(configFile, schema, { upgrade })
+  const { applications } = config.gateway
+
+  const applicationsWithValidOpenApi = applications.filter(({ openapi }) => openapi && openapi.url && openapi.file)
+
+  const fetchOpenApiRequests = applicationsWithValidOpenApi.map(application => fetchOpenApiSchema(application))
+
+  const fetchOpenApiResults = await Promise.allSettled(fetchOpenApiRequests)
+
+  logger.info('Fetching schemas for all applications.')
+
+  fetchOpenApiResults.forEach((result, index) => {
+    const applicationId = applicationsWithValidOpenApi[index].id
+    if (result.status === 'rejected') {
+      logger.error(`Failed to fetch OpenAPI schema for application with id ${bold(applicationId)}: ${result.reason}`)
+    } else {
+      logger.info(`Successfully fetched OpenAPI schema for application with id ${bold(applicationId)}`)
+    }
+  })
+}

package/lib/errors.js

@@ -0,0 +1,18 @@
+import createError from '@fastify/error'
+
+export const ERROR_PREFIX = 'PLT_GATEWAY'
+
+export const FastifyInstanceIsAlreadyListeningError = createError(
+  `${ERROR_PREFIX}_FASTIFY_INSTANCE_IS_ALREADY_LISTENING`,
+  'Fastify instance is already listening. Cannot call "addGatewayOnRouteHook"!'
+)
+export const FailedToFetchOpenAPISchemaError = createError(
+  `${ERROR_PREFIX}_FAILED_TO_FETCH_OPENAPI_SCHEMA`,
+  'Failed to fetch OpenAPI schema from %s'
+)
+export const ValidationErrors = createError(`${ERROR_PREFIX}_VALIDATION_ERRORS`, 'Validation errors: %s')
+export const PathAlreadyExistsError = createError(`${ERROR_PREFIX}_PATH_ALREADY_EXISTS`, 'Path "%s" already exists')
+export const CouldNotReadOpenAPIConfigError = createError(
+  `${ERROR_PREFIX}_COULD_NOT_READ_OPENAPI_CONFIG`,
+  'Could not read openapi config for "%s" application'
+)

package/lib/gateway-hook.js

@@ -0,0 +1,66 @@
+import fp from 'fastify-plugin'
+import rfdc from 'rfdc'
+import { FastifyInstanceIsAlreadyListeningError } from './errors.js'
+
+const deepClone = rfdc()
+
+async function gatewayHookPlugin (app) {
+  const onRoutesHooks = {}
+
+  app.addHook('onRoute', routeOptions => {
+    if (routeOptions.schema) {
+      routeOptions.schema = deepClone(routeOptions.schema)
+    }
+
+    const method = routeOptions.method
+    const openApiPath = routeOptions.config?.openApiPath
+
+    const onRouteHooks = onRoutesHooks[openApiPath]?.[method]
+    if (Array.isArray(onRouteHooks)) {
+      for (const onRouteHook of onRouteHooks) {
+        onRouteHook(routeOptions)
+      }
+    }
+  })
+
+  let isApplicationReady = false
+  app.addHook('onReady', () => {
+    isApplicationReady = true
+  })
+
+  function addGatewayOnRouteHook (openApiPath, methods, hook) {
+    /* c8 ignore next 5 */
+    if (isApplicationReady) {
+      throw new FastifyInstanceIsAlreadyListeningError()
+    }
+
+    if (onRoutesHooks[openApiPath] === undefined) {
+      onRoutesHooks[openApiPath] = {}
+    }
+
+    const routeHooks = onRoutesHooks[openApiPath]
+
+    for (let method of methods) {
+      method = method.toUpperCase()
+
+      if (routeHooks[method] === undefined) {
+        routeHooks[method] = []
+      }
+      routeHooks[method].push(hook)
+    }
+  }
+
+  Object.defineProperty(app.platformatic, 'addGatewayOnRouteHook', {
+    value: addGatewayOnRouteHook,
+    writable: false,
+    configurable: false
+  })
+
+  Object.defineProperty(app.platformatic, 'addComposerOnRouteHook', {
+    value: addGatewayOnRouteHook,
+    writable: false,
+    configurable: false
+  })
+}
+
+export const gatewayHook = fp(gatewayHookPlugin)

package/lib/generator.js

@@ -0,0 +1,127 @@
+import { Generator as ServiceGenerator } from '@platformatic/service'
+
+export class Generator extends ServiceGenerator {
+  constructor (opts) {
+    super({
+      ...opts,
+      module: '@platformatic/gateway'
+    })
+  }
+
+  getDefaultConfig () {
+    const defaultBaseConfig = super.getDefaultConfig()
+
+    return {
+      ...defaultBaseConfig,
+      plugin: false,
+      routes: false,
+      tests: false
+    }
+  }
+
+  async _beforePrepare () {
+    if (this.config.isUpdating) {
+      return
+    }
+
+    await super._beforePrepare()
+
+    this.addEnvVars(
+      {
+        PLT_EXAMPLE_ORIGIN: 'http://127.0.0.1:3043'
+      },
+      { overwrite: false, default: true }
+    )
+
+    this.config.dependencies = {
+      '@platformatic/gateway': `^${this.platformaticVersion}`
+    }
+  }
+
+  async _afterPrepare () {
+    if (this.config.isUpdating) {
+      return
+    }
+
+    await super._afterPrepare()
+    const PLT_ENVIRONMENT_TEMPLATE = `
+import { type FastifyInstance } from 'fastify'
+import { PlatformaticApplication, PlatformaticGatewayConfig } from '@platformatic/gateway'
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    platformatic: PlatformaticApplication<PlatformaticGatewayConfig>
+  }
+}
+`
+
+    const README = `
+# Platformatic Gateway API
+
+This is a generated [Platformatic Gateway](https://docs.platformatic.dev/docs/gateway/overview) application.
+
+## Requirements
+
+Platformatic supports macOS, Linux and Windows ([WSL](https://docs.microsoft.com/windows/wsl/) recommended).
+You'll need to have [Node.js](https://nodejs.org/) >= v18.8.0 or >= v20.6.0
+
+## Setup
+
+1. Install dependencies:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+## Usage
+
+Run the API with:
+
+\`\`\`bash
+npm start
+\`\`\`
+
+### Explore
+- ⚡ The Platformatic Gateway server is running at http://localhost:3042/
+- 📔 View the REST API's Swagger documentation at http://localhost:3042/documentation/      
+`
+
+    this.addFile({ path: '', file: 'plt-env.d.ts', contents: PLT_ENVIRONMENT_TEMPLATE })
+    this.addFile({ path: '', file: 'README.md', contents: README })
+  }
+
+  async _getConfigFileContents () {
+    const config = await super._getConfigFileContents()
+    delete config.service
+    config.$schema = `https://schemas.platformatic.dev/@platformatic/gateway/${this.platformaticVersion}.json`
+
+    config.gateway = {
+      applications: [
+        {
+          id: 'example',
+          origin: `{${this.getEnvVarName('PLT_EXAMPLE_ORIGIN')}}`,
+          openapi: {
+            url: '/documentation/json'
+          }
+        }
+      ],
+      refreshTimeout: 1000
+    }
+
+    if (this.runtime !== null) {
+      config.gateway.applications = this.runtime.applications
+        .filter(applicationMeta => applicationMeta.application.module !== '@platformatic/gateway')
+        .map(applicationMeta => {
+          return {
+            id: applicationMeta.name,
+            openapi: {
+              url: '/documentation/json',
+              prefix: `/${applicationMeta.name}`
+            }
+          }
+        })
+    }
+
+    return config
+  }
+}