@platformatic/watt-extra 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# WattPro
+
+WattPro is an enterprise-ready runtime manager for Platformatic applications that provides production-grade capabilities including monitoring, compliance checking, caching, authentication, and integration with Infrastructure Control Center (ICC) services.
+
+## Overview
+
+WattPro wraps existing Platformatic applications (Service, Composer, Node, or Next.js) to enhance them with enterprise features without requiring any code changes. It acts as a transparent layer that:
+
+- **Monitors** application performance and health metrics
+- **Enforces** compliance policies and security rules
+- **Manages** HTTP caching strategies based on ICC configuration
+- **Handles** authentication and authorization flows
+- **Schedules** cron jobs and periodic tasks
+- **Reports** metadata and telemetry to control plane services
+
+The runtime manager dynamically patches Platformatic configurations at startup to inject these capabilities while maintaining full compatibility with your existing applications.
+
+## Environment Variables
+
+### Required
+
+None.
+
+### Optional
+
+- `PLT_ICC_URL` - Infrastructure Control Center URL for connecting to control plane services. When not set, WattPro runs in standalone mode without ICC integration
+- `PLT_APP_NAME` - Unique identifier for your application instance. Optional when `PLT_ICC_URL` is set - if not provided, it will be automatically determined from Kubernetes labels following these rules:
+  1. Uses `app.kubernetes.io/instance` label first
+  2. Falls back to ReplicaSet naming convention (`{app-name}-{hash}`)
+- `PLT_APP_DIR` - Application directory (defaults to current working directory)
+- `PLT_TEST_TOKEN` - JWT token for authentication in non-Kubernetes environments
+- `PLT_LOG_LEVEL` - Logging level for the application
+- `PLT_CACHE_CONFIG` - HTTP caching configuration
+
+### Standalone Mode
+
+WattPro can run without connecting to an Infrastructure Control Center (ICC). When `PLT_ICC_URL` is not set:
+
+- No ICC connection attempts are made
+- All ICC-dependent plugins (alerts, compliance, metadata, scheduler) skip their operations
+- The application runs with local configuration only
+
+## Installation
+
+```bash
+npm install @platformatic/wattpro
+```
+
+## Usage
+
+Add a script to your package.json:
+
+```json
+"scripts": {
+  "wattpro": "wattpro start"
+}
+```
+
+Then run:
+
+```bash
+npm run wattpro
+```
+
+### Command Line Interface
+
+WattPro provides a command-line interface:
+
+```bash
+# Show help
+wattpro --help
+
+# Start the runtime manager
+wattpro start
+
+# Set log level
+wattpro start --log-level=debug
+
+# Set ICC URL
+wattpro start --icc-url=http://icc-server:3000
+
+# Set application name
+wattpro start --app-name=my-application
+
+# Set application directory. This is useful for development and test
+wattpro start --app-dir=/path/to/application
+```

package/app.js

@@ -0,0 +1,124 @@
+import avvio from 'avvio'
+import { setTimeout } from 'node:timers/promises'
+import init from './plugins/init.js'
+import env from './plugins/env.js'
+import metadata from './plugins/metadata.js'
+import compliancy from './plugins/compliancy.js'
+import scheduler from './plugins/scheduler.js'
+import auth from './plugins/auth.js'
+import update from './plugins/update.js'
+import alert from './plugins/alerts.js'
+import flamegraphs from './plugins/flamegraphs.js'
+
+async function buildApp (logger) {
+  const app = {
+    log: logger,
+  }
+
+  avvio(app)
+
+  app
+    .use(env)
+    .use(auth)
+    .use(init)
+    .use(alert)
+    .use(metadata)
+    .use(compliancy)
+    .use(scheduler)
+    .use(update)
+    .use(flamegraphs)
+
+  await app.ready()
+
+  app.startRuntime = async function startRuntime () {
+    app.log.info('Starting Runtime -app')
+    try {
+      app.log.info('Spawning the app')
+      await app.wattpro.spawn()
+    } catch (err) {
+      app.log.error(err, 'Failed to spawn the app')
+      throw new Error('Failed to spawn the app: ' + err.message)
+    }
+  }
+
+  app.sendToICC = async function sendToICC () {
+    // Skip if ICC is not configured
+    if (!app.env.PLT_ICC_URL) {
+      app.log.info('PLT_ICC_URL not set, skipping ICC operations')
+      return
+    }
+
+    if (!app.wattpro.runtime) {
+      throw new Error('Runtime not started, cannot send to ICC')
+    }
+    try {
+      if (!app.instanceConfig) {
+        await app.initApplication()
+      }
+      await app.connectToUpdates()
+      await app.sendMetadata()
+      await app.checkCompliancy()
+      await app.sendSchedulerInfo()
+    } catch (err) {
+      app.log.error({ err }, 'Failed in sending data to ICC')
+      throw err
+    }
+  }
+
+  app.sendToICCWithRetry = async function sendToICCWithRetry () {
+    // Skip all ICC operations if PLT_ICC_URL is not set
+    if (!app.env.PLT_ICC_URL) {
+      app.log.info('PLT_ICC_URL not set, skipping all ICC operations')
+      return
+    }
+
+    const baseRetryInterval = Number(app.env.PLT_ICC_RETRY_TIME)
+    const maxRetryInterval = 60000 // Max retry interval: 1 minute
+
+    let currentRetryInterval = baseRetryInterval
+    let retries = 0
+    let capReached = false
+
+    while (true) {
+      // Continue indefinitely
+      retries++
+
+      try {
+        await this.sendToICC()
+        logger.info('Successfully sent info to ICC after retry')
+        return
+      } catch (err) {
+        if (!capReached) {
+          const waitFor = 200 * Math.pow(2, retries)
+          if (waitFor >= maxRetryInterval) {
+            capReached = true
+            currentRetryInterval = maxRetryInterval
+          } else {
+            currentRetryInterval = waitFor
+          }
+        }
+        logger.error(
+          {
+            err: err.message,
+            attemptNumber: retries,
+            nextRetryMs: currentRetryInterval,
+          },
+          `Failed to send info to ICC, retrying in ${currentRetryInterval}ms`
+        )
+        await setTimeout(currentRetryInterval)
+      }
+    }
+  }
+
+  app.close = async function close () {
+    app.log.info('Closing runtime')
+    if (app.wattpro.runtime) {
+      await app.wattpro.close()
+    }
+    await app.closeUpdates()
+  }
+
+  return app
+}
+
+export default buildApp

package/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import commist from 'commist'
+import minimist from 'minimist'
+import { resolve, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import helpMeInit from 'help-me'
+import { readFileSync } from 'node:fs'
+import { start, logger } from './index.js'
+import { getSimpleBanner } from './lib/banner.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const helpMe = helpMeInit({
+  dir: join(__dirname, 'help'),
+  ext: '.txt'
+})
+
+const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+const commistInstance = commist()
+
+function version () {
+  console.log(getSimpleBanner(pkg.version))
+  logger.info(`WattExtra v${pkg.version}`)
+}
+
+// Handle start command
+async function startCommand (argv) {
+  const banner = getSimpleBanner(pkg.version)
+  console.log(banner)
+
+  const args = minimist(argv, {
+    alias: {
+      h: 'help',
+      l: 'log-level',
+      i: 'icc-url',
+      a: 'app-name',
+      d: 'app-dir'
+    },
+    boolean: ['help'],
+    string: ['log-level', 'icc-url', 'app-name', 'app-dir'],
+    default: {
+      'log-level': 'info',
+      'app-dir': process.cwd()
+    }
+  })
+
+  logger.debug({ args, argv }, 'Start command arguments')
+
+  if (args.help) {
+    helpMe.toStdout('start')
+    return true
+  }
+
+  // Set environment variables based on CLI options
+  if (args['log-level']) {
+    process.env.PLT_LOG_LEVEL = args['log-level']
+  }
+
+  if (args['icc-url']) {
+    process.env.PLT_ICC_URL = args['icc-url']
+  }
+
+  if (args['app-name']) {
+    process.env.PLT_APP_NAME = args['app-name']
+  }
+
+  if (args['app-dir']) {
+    process.env.PLT_APP_DIR = resolve(args['app-dir']) // Ensure the path is absolute
+  }
+
+  await start()
+  return true
+}
+
+// Handle help command
+function help (args) {
+  // Make sure args exists and has the expected structure
+  const command = args && args._ ? args._[0] : undefined
+  helpMe.toStdout(command || 'watt-extra')
+}
+
+// Register commands
+commistInstance.register('start', startCommand)
+commistInstance.register('help', help)
+commistInstance.register('version', version)
+commistInstance.register('-h', help)
+commistInstance.register('--help', help)
+
+async function run () {
+  try {
+    logger.debug('Parsing command line arguments')
+    const args = process.argv.slice(2)
+
+    // Show help if no arguments are provided
+    if (args.length === 0) {
+      helpMe.toStdout('watt-extra')
+      return
+    }
+
+    // Handle help flag directly
+    if (args[0] === '--help' || args[0] === '-h') {
+      helpMe.toStdout('watt-extra')
+      return
+    }
+
+    // Handle the case where the first argument is a recognized command
+    if (args.length > 0) {
+      const command = args[0]
+
+      if (command === 'start') {
+        // Pass the rest of the arguments to the start command
+        await startCommand(args.slice(1))
+        return
+      }
+
+      if (command === 'help') {
+        // Handle the 'help' command with optional subcommand
+        const subcommand = args[1]
+        helpMe.toStdout(subcommand || 'watt-extra')
+        return
+      }
+
+      if (command === 'version') {
+        version()
+        return
+      }
+
+      logger.error(`Command "${command}" does not exist`)
+      helpMe.toStdout('watt-extra')
+      process.exit(1)
+    }
+
+    await commistInstance.parseAsync(args)
+  } catch (err) {
+    logger.error({ err }, 'Error running watt-extra')
+    process.exit(1)
+  }
+}
+
+run()