@platformatic/watt-admin 0.6.0-alpha.1 → 0.6.0-alpha.3

package/README.md

@@ -14,7 +14,7 @@ After installing the project dependencies, you can run the tool directly:
 
 To run the CLI on a custom port, you can just pass it as an argument with `./cli.js --port 4321`.
 
-To record a flamegraph session, and choose to profile either the `cpu` or the `heap`, you can run the CLI with `./cli.js --record --flamegraph heap`. Once you will stop the process, an HTML one-file bundle will be auto-generated, and you will be able to navigate (even offline) the `watt-admin` app, looking at the flamegraph and at the metrics stored for the whole time you have run the CLI.
+To record a flamegraph session, and choose to profile either the `cpu` or the `heap`, you can run the CLI with `./cli.js --record --profile heap`. Once you will stop the process, an HTML one-file bundle will be auto-generated, and you will be able to navigate (even offline) the `watt-admin` app, looking at the flamegraph and at the metrics stored for the whole time you have run the CLI.
 
 The tool is also available as a binary when installed globally or linked:
 

package/cli.d.ts

@@ -0,0 +1,3 @@
+import type { Runtime } from '@platformatic/control'
+
+export default function main (): Promise<Runtime | null>

package/cli.js

@@ -2,7 +2,7 @@
 
 'use strict'
 
-import { pathToFileURL } from 'url'
+import esmain from 'es-main'
 import { RuntimeApiClient } from '@platformatic/control'
 import { select } from '@inquirer/prompts'
 import { start } from './lib/start.js'
@@ -137,7 +137,7 @@ export default async function main () {
 }
 
 // Execute the main function if this script is run directly
-if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (esmain(import.meta)) {
   main().then((selectedRuntime) => {
     if (!selectedRuntime) {
       return

package/lib/start.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeApiClient } from '@platformatic/control'
+
+export declare function start (client: RuntimeApiClient, selectedRuntime: string): Promise<void>

package/lib/start.js

@@ -52,7 +52,9 @@ export async function start (client, selectedRuntime) {
   }
 
   const configFile = join(__dirname, '..', 'watt.json')
-  const server = await create(configFile)
+  const server = await create(configFile, undefined, {
+    setupSignals: false
+  })
   entrypointUrl = await server.start()
 
   if (record) {
@@ -64,6 +66,9 @@ export async function start (client, selectedRuntime) {
 
       // Always clean up the client
       await client.close()
+
+      // Then stop the server
+      await server.close()
     })
 
     const { statusCode, body } = await requestRecord('start')

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@platformatic/watt-admin",
-  "version": "0.6.0-alpha.1",
+  "version": "0.6.0-alpha.3",
   "scripts": {
     "prepublishOnly": "npm run clean && npm run build",
     "dev": "wattpm dev",
@@ -28,46 +28,48 @@
     "@platformatic/gateway": "^3.11.0",
     "@platformatic/runtime": "^3.11.0",
     "@platformatic/service": "^3.11.0",
+    "@platformatic/ui-components": "^0.19.1",
     "@platformatic/vite": "^3.11.0",
+    "@platformatic/wattpm-pprof-capture": "^3.13.0",
     "@scalar/api-reference-react": "^0.7.55",
+    "@vitejs/plugin-react": "^5.0.4",
+    "amaro": "^1.1.4",
+    "autoprefixer": "^10.4.21",
     "close-with-grace": "^2.3.0",
+    "d3": "^7.9.0",
+    "dayjs": "^1.11.18",
+    "es-main": "^1.4.0",
     "fastify": "^5.6.1",
     "pprof-format": "^2.2.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-pprof": "^1.1.0",
+    "react-router-dom": "^7.9.3",
     "react-use-websocket": "^4.13.0",
     "split2": "^4.2.0",
+    "tailwindcss": "^3.4.18",
     "undici": "^7.16.0",
-    "wattpm": "^3.11.0"
+    "use-error-boundary": "^2.0.6",
+    "vite": "^7.1.9",
+    "vite-plugin-singlefile": "^2.3.0",
+    "wattpm": "^3.11.0",
+    "zustand": "^5.0.8"
   },
   "devDependencies": {
     "@fastify/type-provider-json-schema-to-ts": "^5.0.0",
-    "@platformatic/ui-components": "^0.19.1",
-    "@platformatic/wattpm-pprof-capture": "^3.13.0",
     "@playwright/test": "^1.56.0",
     "@types/d3": "^7.4.3",
     "@types/node": "^22",
     "@types/react-dom": "^19.2.1",
     "@types/split2": "^4.2.3",
     "@types/ws": "^8.18.1",
-    "@vitejs/plugin-react": "^5.0.4",
-    "autoprefixer": "^10.4.21",
-    "d3": "^7.9.0",
-    "dayjs": "^1.11.18",
     "eslint": "^9.37.0",
     "fastify-tsconfig": "^3.0.0",
     "massimo-cli": "^1.0.1",
     "neostandard": "^0.12.2",
     "playwright": "^1.56.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-router-dom": "^7.9.3",
-    "tailwindcss": "^3.4.18",
     "typescript": "^5.9.3",
-    "use-error-boundary": "^2.0.6",
-    "vite": "^7.1.9",
-    "vite-plugin-singlefile": "^2.3.0",
-    "vitest": "^3.2.4",
-    "zustand": "^5.0.8"
+    "vitest": "^3.2.4"
   },
   "bin": {
     "watt-admin": "./cli.js"

package/renovate.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:base"
+  ],
+  "packageRules": [
+    {
+      "groupName": "Safe automerge",
+      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+      "automerge": true
+    }
+  ],
+  "lockFileMaintenance": {
+    "enabled": true,
+    "automerge": true
+  }
+}

package/watt.json

@@ -7,13 +7,21 @@
   "logger": {
     "level": "info"
   },
-  "autoload": {
-    "path": "web",
-    "mappings": {
-      "backend": {
-        "id": "backend",
-        "useHttp": true
-      }
+  "entrypoint": "composer",
+  "applications": [
+    {
+      "id": "backend",
+      "path": "./web/backend",
+      "useHttp": true,
+      "nodeOptions": "--import=amaro/strip"
+    },
+    {
+      "id": "composer",
+      "path": "./web/composer"
+    },
+    {
+      "id": "frontend",
+      "path": "./web/frontend"
     }
-  }
+  ]
 }

package/web/backend/global.d.ts

@@ -0,0 +1,17 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { FastifyInstance } from 'fastify'
+import type { PlatformaticApp, PlatformaticServiceConfig } from '@platformatic/service'
+import type { Mode, Profile } from './schemas/index.ts'
+import type { MappedMetrics } from './utils/metrics-helpers.ts'
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    platformatic: PlatformaticApp<PlatformaticServiceConfig>
+    metricsInterval: NodeJS.Timeout
+    loaded: { mode?: Mode, metrics: MappedMetrics, type?: Profile }
+  }
+
+  interface FastifySchema {
+    hide?: boolean
+  }
+}

package/web/backend/plugins/metrics.ts

@@ -0,0 +1,15 @@
+import type { FastifyInstance } from 'fastify'
+import { getMetrics } from '../utils/metrics.ts'
+import { MS_WAITING } from '../utils/constants.ts'
+
+export default async function (fastify: FastifyInstance) {
+  fastify.decorate('loaded', { metrics: {} })
+
+  fastify.decorate('metricsInterval', setInterval(() => getMetrics(fastify), MS_WAITING))
+
+  fastify.addHook('onClose', async () => {
+    // If the following log is not called, please run the project directly through the `wattpm` binary (ref. https://github.com/platformatic/platformatic/issues/3751)
+    fastify.log.info('Closing the backend...')
+    clearInterval(fastify.metricsInterval)
+  })
+}

package/web/backend/plugins/websocket.ts

@@ -0,0 +1,6 @@
+import websocket from '@fastify/websocket'
+import type { FastifyInstance } from 'fastify'
+
+export default async function (fastify: FastifyInstance) {
+  await fastify.register(websocket)
+}

package/web/backend/routes/metrics.ts

@@ -0,0 +1,46 @@
+import type { FastifyInstance } from 'fastify'
+import type { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { metricResponseSchema, pidParamSchema } from '../schemas/index.ts'
+import type { MetricsResponse } from '../schemas/index.ts'
+
+export default async function (fastify: FastifyInstance) {
+  const typedFastify = fastify.withTypeProvider<JsonSchemaToTsProvider>()
+  const emptyMetrics: MetricsResponse = { dataCpu: [], dataLatency: [], dataMem: [], dataReq: [], dataKafka: [], dataUndici: [], dataWebsocket: [], dataNodejs: [] }
+
+  typedFastify.get('/runtimes/:pid/metrics', {
+    schema: { params: pidParamSchema, response: { 200: metricResponseSchema } },
+  }, async ({ params: { pid } }) => fastify.loaded.metrics[pid]?.aggregated || emptyMetrics)
+
+  typedFastify.get('/runtimes/:pid/metrics/:serviceId', {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          pid: { type: 'number' },
+          serviceId: { type: 'string' }
+        },
+        required: ['pid', 'serviceId']
+      },
+      response: { 200: metricResponseSchema }
+    }
+  }, async ({ params: { pid, serviceId } }) => {
+    return fastify.loaded.metrics[pid]?.services[serviceId]?.all || emptyMetrics
+  })
+
+  typedFastify.get('/runtimes/:pid/metrics/:serviceId/:workerId', {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          pid: { type: 'number' },
+          serviceId: { type: 'string' },
+          workerId: { type: 'number' },
+        },
+        required: ['pid', 'serviceId', 'workerId']
+      },
+      response: { 200: metricResponseSchema }
+    }
+  }, async ({ params: { pid, serviceId, workerId } }) => {
+    return fastify.loaded.metrics[pid]?.services[serviceId]?.[workerId] || emptyMetrics
+  })
+}

package/web/backend/routes/proxy.ts

@@ -0,0 +1,41 @@
+import type { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { RuntimeApiClient } from '@platformatic/control'
+import type { FastifyInstance } from 'fastify'
+
+export default async function (fastify: FastifyInstance) {
+  const typedFastify = fastify.withTypeProvider<JsonSchemaToTsProvider>()
+  const api = new RuntimeApiClient()
+
+  typedFastify.removeContentTypeParser(['application/json', 'text/*'])
+  typedFastify.addContentTypeParser('*', { parseAs: 'buffer' }, async (_request: unknown, body: unknown) => body)
+
+  typedFastify.all('/proxy/:pid/services/:serviceId/*', {
+    schema: {
+      hide: true, // needed since the client generation fails to properly handle the '*' wildcard
+    }
+  }, async (request, reply) => {
+    const { pid, serviceId, '*': requestUrl } = request.params as { pid: number, serviceId: string, '*': string } // cast needed because we can't define a valid json schema with the '*' wildcard
+
+    delete request.headers.connection
+    delete request.headers['content-length']
+    delete request.headers['content-encoding']
+    delete request.headers['transfer-encoding']
+
+    const injectParams = {
+      method: request.method,
+      url: '/' + requestUrl,
+      headers: request.headers,
+      query: request.query,
+      body: request.body
+    } as Parameters<typeof api.injectRuntime>[2]
+
+    fastify.log.info({ pid, serviceId, injectParams }, 'runtime request proxy')
+
+    const res = await api.injectRuntime(pid, serviceId, injectParams)
+
+    delete res.headers['content-length']
+    delete res.headers['transfer-encoding']
+
+    return reply.code(res.statusCode).headers(res.headers).send(res.body)
+  })
+}

package/web/backend/routes/root.ts

@@ -0,0 +1,204 @@
+import type { FastifyInstance } from 'fastify'
+import type { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { RuntimeApiClient } from '@platformatic/control'
+import { getPidToLoad, getSelectableRuntimes } from '../utils/runtimes.ts'
+import { writeFile, readFile } from 'fs/promises'
+import { checkRecordState } from '../utils/states.ts'
+import { join } from 'path'
+import { pidParamSchema, selectableRuntimeSchema, modeSchema, profileSchema } from '../schemas/index.ts'
+
+const __dirname = import.meta.dirname
+
+export default async function (fastify: FastifyInstance) {
+  const typedFastify = fastify.withTypeProvider<JsonSchemaToTsProvider>()
+
+  // FIXME: types have not been properly implemented in `@platformatic/control` and they should be updated as form the cast in the following line
+  const api = new RuntimeApiClient() as RuntimeApiClient & { startApplicationProfiling: (...args: unknown[]) => Promise<unknown>, stopApplicationProfiling: (...args: unknown[]) => Promise<string> }
+
+  typedFastify.get('/runtimes', {
+    schema: {
+      querystring: {
+        type: 'object',
+        properties: {
+          includeAdmin: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+      },
+      response: { 200: { type: 'array', items: selectableRuntimeSchema } }
+    }
+  }, async (request) => getSelectableRuntimes(await api.getRuntimes(), request.query.includeAdmin))
+
+  typedFastify.get('/runtimes/:pid/health', {
+    schema: {
+      params: pidParamSchema,
+      response: {
+        200: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            status: {
+              type: 'string',
+              enum: ['OK', 'KO'],
+              description: "Status can only be 'OK' or 'KO'"
+            }
+          },
+          required: ['status']
+        }
+      }
+    }
+  }, async ({ params: { pid } }) => {
+    const ok = { status: 'OK' as const }
+    const ko = { status: 'KO' as const }
+
+    try {
+      const result = await api.getMatchingRuntime({ pid: pid.toString() })
+      return (result.pid === pid) ? ok : ko
+    } catch {
+      return ko
+    }
+  })
+
+  typedFastify.get('/runtimes/:pid/services', {
+    schema: {
+      params: pidParamSchema,
+      response: {
+        200: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['entrypoint', 'production', 'applications'],
+          properties: {
+            entrypoint: {
+              type: 'string'
+            },
+            production: {
+              type: 'boolean'
+            },
+            applications: {
+              type: 'array',
+              items: {
+                anyOf: [
+                  {
+                    additionalProperties: false,
+                    type: 'object',
+                    required: ['id', 'type', 'status', 'version', 'localUrl', 'entrypoint', 'dependencies'],
+                    properties: {
+                      id: {
+                        type: 'string'
+                      },
+                      type: {
+                        type: 'string'
+                      },
+                      status: {
+                        type: 'string'
+                      },
+                      version: {
+                        type: 'string'
+                      },
+                      localUrl: {
+                        type: 'string'
+                      },
+                      entrypoint: {
+                        type: 'boolean'
+                      },
+                      workers: {
+                        type: 'number'
+                      },
+                      url: {
+                        type: 'string'
+                      },
+                      dependencies: {
+                        type: 'array',
+                        items: { type: 'string' }
+                      }
+                    }
+                  },
+                  {
+                    additionalProperties: false,
+                    type: 'object',
+                    required: ['id', 'status'],
+                    properties: {
+                      id: {
+                        type: 'string'
+                      },
+                      status: {
+                        type: 'string'
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  }, async (request) => api.getRuntimeApplications(request.params.pid))
+
+  typedFastify.get('/runtimes/:pid/openapi/:serviceId', {
+    schema: {
+      params: { type: 'object', properties: { pid: { type: 'number' }, serviceId: { type: 'string' } }, required: ['pid', 'serviceId'] }
+    }
+  }, async ({ params: { pid, serviceId } }) => api.getRuntimeOpenapi(pid, serviceId))
+
+  typedFastify.post('/runtimes/:pid/restart', {
+    schema: { params: pidParamSchema, body: { type: 'object' } }
+  }, async (request) => {
+    try {
+      await api.restartRuntime(request.params.pid)
+    } catch (err) {
+      fastify.log.warn({ err }, 'Issue restarting the runtime')
+    }
+  })
+
+  typedFastify.post('/record/:pid', {
+    schema: {
+      params: pidParamSchema,
+      body: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { mode: modeSchema, profile: profileSchema },
+        required: ['mode', 'profile']
+      }
+    }
+  }, async ({ body: { mode, profile: type }, params: { pid } }) => {
+    const from = fastify.loaded.mode
+    const to = mode
+    if (!checkRecordState({ from, to })) {
+      return fastify.log.error({ from, to }, 'Invalid record state machine transition')
+    }
+
+    const { applications } = await api.getRuntimeApplications(pid)
+    fastify.loaded.mode = mode
+    if (mode === 'start') {
+      for (const { id } of applications) {
+        await api.startApplicationProfiling(pid, id, { type })
+      }
+      fastify.loaded.type = type
+      fastify.loaded.metrics = {}
+    }
+
+    if (mode === 'stop') {
+      try {
+        const runtimes = getSelectableRuntimes(await api.getRuntimes(), false)
+        const services = await api.getRuntimeApplications(getPidToLoad(runtimes))
+
+        const profile: Record<string, Uint8Array> = {}
+        for (const { id } of applications) {
+          const profileData = Buffer.from(await api.stopApplicationProfiling(pid, id, { type }))
+          await writeFile(join(__dirname, '..', '..', 'frontend', 'dist', `${fastify.loaded.type}-profile-${id}.pb`), profileData)
+          profile[id] = new Uint8Array(profileData)
+        }
+
+        const loadedJson = JSON.stringify({ runtimes, services, metrics: fastify.loaded.metrics[getPidToLoad(runtimes)], profile, type })
+
+        const scriptToAppend = `  <script>window.LOADED_JSON=${loadedJson}</script>\n</body>`
+        const bundlePath = join(__dirname, '..', '..', 'frontend', 'dist', 'index.html')
+        await writeFile(bundlePath, (await readFile(bundlePath, 'utf8')).replace('</body>', scriptToAppend), 'utf8')
+      } catch (err) {
+        fastify.log.error({ err }, 'Unable to save the loaded JSON')
+      }
+    }
+  })
+}

package/web/backend/routes/ws.ts

@@ -0,0 +1,45 @@
+import type { WebSocket } from 'ws'
+import split2 from 'split2'
+import type { FastifyInstance } from 'fastify'
+import type { JsonSchemaToTsProvider } from '@fastify/type-provider-json-schema-to-ts'
+import { RuntimeApiClient } from '@platformatic/control'
+import { pidParamSchema } from '../schemas/index.ts'
+import type { PidParam } from '../schemas/index.ts'
+import { pipeline } from 'node:stream/promises'
+
+export default async function (fastify: FastifyInstance) {
+  const typedFastify = fastify.withTypeProvider<JsonSchemaToTsProvider>()
+  const api = new RuntimeApiClient()
+
+  const wsSendAsync = (socket: WebSocket, data: string): Promise<void> => new Promise((resolve, reject) => setTimeout(() => socket.send(data, (err) => (err)
+    ? reject(err)
+    : resolve()
+  ), 100)
+  )
+
+  typedFastify.get<{ Params: PidParam }>('/runtimes/:pid/logs/ws', {
+    schema: { params: pidParamSchema },
+    websocket: true
+  }, async (socket, { params: { pid } }) => {
+    try {
+      const clientStream = api.getRuntimeLiveLogsStream(pid)
+
+      socket.on('close', () => {
+        clientStream.destroy()
+      })
+
+      await pipeline(
+        clientStream,
+        split2(),
+        async function * (source: AsyncIterable<string>) {
+          for await (const line of source) {
+            await wsSendAsync(socket, line)
+          }
+        }
+      )
+    } catch (error) {
+      fastify.log.error({ error }, 'fatal error on runtime logs ws')
+      socket.close()
+    }
+  })
+}