@getvision/adapter-fastify 0.0.0-develop-20251031183955

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@getvision/adapter-fastify",
+  "version": "0.0.0-develop-20251031183955",
+  "description": "Fastify adapter for Vision Dashboard",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "vision",
+    "fastify",
+    "observability",
+    "tracing",
+    "monitoring"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@fastify/request-context": "^6.2.1",
+    "fastify-plugin": "^5.1.0",
+    "@getvision/core": "0.0.1"
+  },
+  "peerDependencies": {
+    "fastify": "^5.6.1",
+    "zod": "^3.22.4"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "fastify": "^5.6.1",
+    "typescript": "^5.9.3",
+    "zod": "^3.24.4"
+  },
+  "config": {}
+}

package/src/fastify.d.ts

@@ -0,0 +1,12 @@
+import type { VisionCore, Trace } from '@getvision/core';
+
+declare module '@fastify/request-context' {
+  interface RequestContextData {
+    visionTrace: {
+      vision: VisionCore;
+      trace: Trace;
+      traceId: string;
+      rootSpanId: string;
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,489 @@
+import type { FastifyInstance, FastifyPluginAsync } from 'fastify'
+import fp from 'fastify-plugin'
+import {
+  VisionCore,
+  autoDetectPackageInfo,
+  autoDetectIntegrations,
+  detectDrizzle,
+  startDrizzleStudio,
+  stopDrizzleStudio,
+} from '@getvision/core'
+import type {
+  RequestBodySchema,
+  RouteMetadata,
+  SchemaField,
+  Trace,
+  VisionFastifyOptions,
+  ServiceDefinition,
+} from '@getvision/core'
+import { fastifyRequestContext, requestContext } from '@fastify/request-context'
+
+interface VisionContext {
+  vision: VisionCore
+  trace: Trace
+  traceId: string
+  rootSpanId: string
+}
+
+export function getVisionContext(): VisionContext {
+  const ctx = requestContext.get('visionTrace')
+  if (!ctx) {
+    throw new Error('Vision context not available. Make sure visionPlugin is registered.')
+  }
+  return ctx
+}
+
+export function useVisionSpan() {
+  const { vision, traceId, rootSpanId } = getVisionContext()
+  const tracer = vision.getTracer()
+
+  return <T>(
+    name: string,
+    attributes: Record<string, any> = {},
+    fn: () => T
+  ): T => {
+    const span = tracer.startSpan(name, traceId, rootSpanId)
+
+    for (const [key, value] of Object.entries(attributes)) {
+      tracer.setAttribute(span.id, key, value)
+    }
+
+    try {
+      const result = fn()
+      const completedSpan = tracer.endSpan(span.id)
+
+      if (completedSpan) {
+        vision.getTraceStore().addSpan(traceId, completedSpan)
+      }
+
+      return result
+    } catch (error) {
+      tracer.setAttribute(span.id, 'error', true)
+      tracer.setAttribute(
+        span.id,
+        'error.message',
+        error instanceof Error ? error.message : String(error)
+      )
+      const completedSpan = tracer.endSpan(span.id)
+
+      if (completedSpan) {
+        vision.getTraceStore().addSpan(traceId, completedSpan)
+      }
+
+      throw error
+    }
+  }
+}
+
+
+let visionInstance: VisionCore | null = null
+
+export function getVisionInstance(): VisionCore | null {
+  return visionInstance
+}
+
+const visionPluginImpl: FastifyPluginAsync<VisionFastifyOptions> = async (fastify, options) => {
+  const {
+    port = 9500,
+    enabled = true,
+    maxTraces = 1000,
+    maxLogs = 10000,
+    logging = true,
+    cors = true,
+  } = options
+
+  if (!enabled) {
+    return
+  }
+
+  if (!visionInstance) {
+    visionInstance = new VisionCore({
+      port,
+      maxTraces,
+      maxLogs,
+    })
+  }
+
+  const vision = visionInstance
+
+  await fastify.register(fastifyRequestContext, {
+    hook: 'onRequest',
+  })
+
+  fastify.addHook('onReady', async () => {
+    // Auto-detect service info
+    const pkgInfo = autoDetectPackageInfo()
+    const autoDetectedIntegrations = autoDetectIntegrations()
+
+    // Merge with user-provided config
+    const serviceName = options.service?.name || pkgInfo.name
+    const serviceVersion = options.service?.version || pkgInfo.version
+    const serviceDesc = options.service?.description
+    const integrations = {
+      ...autoDetectedIntegrations,
+      ...options.service?.integrations,
+    }
+
+    // Filter out undefined values from integrations
+    const cleanIntegrations: Record<string, string> = {}
+    for (const [key, value] of Object.entries(integrations)) {
+      if (value !== undefined) {
+        cleanIntegrations[key] = value
+      }
+    }
+
+    // Detect and optionally start Drizzle Studio
+    const drizzleInfo = detectDrizzle()
+    let drizzleStudioUrl: string | undefined
+
+    if (drizzleInfo.detected) {
+      console.log(`🗄️  Drizzle detected (${drizzleInfo.configPath})`)
+
+      if (options.drizzle?.autoStart) {
+        const drizzlePort = options.drizzle.port || 4983
+        const started = startDrizzleStudio(drizzlePort)
+        if (started) {
+          // Drizzle Studio uses local.drizzle.studio domain (with HTTPS)
+          drizzleStudioUrl = 'https://local.drizzle.studio'
+        }
+      } else {
+        console.log('💡 Tip: Enable Drizzle Studio auto-start with drizzle: { autoStart: true }')
+        drizzleStudioUrl = 'https://local.drizzle.studio'
+      }
+    }
+
+    // Set app status with service metadata
+    vision.setAppStatus({
+      name: serviceName,
+      version: serviceVersion,
+      description: serviceDesc,
+      running: true,
+      pid: process.pid,
+      metadata: {
+        framework: 'Fastify',
+        integrations: Object.keys(cleanIntegrations).length > 0 ? cleanIntegrations : undefined,
+        drizzle: drizzleInfo.detected
+          ? {
+              detected: true,
+              configPath: drizzleInfo.configPath,
+              studioUrl: drizzleStudioUrl,
+              autoStarted: options.drizzle?.autoStart || false,
+            }
+          : undefined,
+      },
+    })
+
+    // Cleanup on exit
+    process.on('SIGINT', () => {
+      stopDrizzleStudio()
+      process.exit(0)
+    })
+
+    process.on('SIGTERM', () => {
+      stopDrizzleStudio()
+      process.exit(0)
+    })
+  })
+
+  const CAPTURE_KEY = Symbol.for('vision.fastify.routes')
+  const captured: Array<{ method: string; url: string; schema?: any; handlerName?: string }> =
+    ((fastify as any)[CAPTURE_KEY] = (fastify as any)[CAPTURE_KEY] || [])
+
+  fastify.addHook('onRoute', (routeOpts: any) => {
+    const methods = Array.isArray(routeOpts.method) ? routeOpts.method : [routeOpts.method]
+    for (const m of methods) {
+      const method = (m || '').toString().toUpperCase()
+      if (!method || method === 'HEAD' || method === 'OPTIONS') continue
+      captured.push({
+        method,
+        url: routeOpts.url as string,
+        schema: routeOpts.schema,
+        handlerName: routeOpts.handler?.name || 'anonymous',
+      })
+    }
+  })
+
+  if (cors) {
+    fastify.options('/*', async (request, reply) => {
+      reply
+        .header('Access-Control-Allow-Origin', '*')
+        .header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS')
+        .header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session')
+        .header('Access-Control-Expose-Headers', 'X-Vision-Trace-Id, X-Vision-Session')
+        .code(204)
+        .send()
+    })
+
+    fastify.addHook('onRequest', async (request, reply) => {
+      reply.header('Access-Control-Allow-Origin', '*')
+      reply.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS')
+      reply.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session')
+      reply.header('Access-Control-Expose-Headers', 'X-Vision-Trace-Id, X-Vision-Session')
+    })
+  }
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    if (request.method === 'OPTIONS') return
+
+    const startTime = Date.now();
+    (request as any).visionStartTime = startTime
+
+    const trace = vision.createTrace(request.method, request.url)
+
+    reply.header('X-Vision-Trace-Id', trace.id)
+
+    const tracer = vision.getTracer()
+    const rootSpan = tracer.startSpan('http.request', trace.id);
+
+    request.requestContext.set('visionTrace', {
+      vision,
+      trace,
+      traceId: trace.id,
+      rootSpanId: rootSpan.id,
+    })
+
+    tracer.setAttribute(rootSpan.id, 'http.method', request.method)
+    tracer.setAttribute(rootSpan.id, 'http.path', request.url)
+    tracer.setAttribute(rootSpan.id, 'http.url', request.url)
+
+    if (request.query && Object.keys(request.query).length > 0) {
+      tracer.setAttribute(rootSpan.id, 'http.query', request.query)
+    }
+
+    const requestMeta = {
+      method: request.method,
+      url: request.url,
+      headers: request.headers,
+      query: Object.keys(request.query || {}).length ? request.query : undefined,
+      body: request.body,
+    }
+    tracer.setAttribute(rootSpan.id, 'http.request', requestMeta)
+    trace.metadata = { ...trace.metadata, request: requestMeta }
+
+    const sessionId = request.headers['x-vision-session']
+    if (sessionId) {
+      tracer.setAttribute(rootSpan.id, 'session.id', sessionId)
+      trace.metadata = { ...trace.metadata, sessionId }
+    }
+
+    if (logging) {
+      const parts = [`method=${request.method}`, `path=${request.url}`]
+      if (sessionId) parts.push(`sessionId=${sessionId}`)
+      parts.push(`traceId=${trace.id}`)
+      console.info(`INF starting request ${parts.join(' ')}`)
+    }
+  })
+
+  fastify.addHook('onResponse', async (request, reply) => {
+    if (request.method === 'OPTIONS') return
+
+    const startTime = (request as any).visionStartTime
+    const context = request.requestContext.get('visionTrace') as VisionContext | undefined
+    if (!context || !startTime) return
+    const { vision, trace, traceId, rootSpanId } = context
+    const tracer = vision.getTracer()
+
+    try {
+      const duration = Date.now() - startTime
+      const rootSpan = tracer.getSpan(rootSpanId)
+      if (!rootSpan) return
+
+      tracer.setAttribute(rootSpan.id, 'http.status_code', reply.statusCode)
+
+      const responseMeta = {
+        status: reply.statusCode,
+        headers: reply.getHeaders(),
+      }
+      tracer.setAttribute(rootSpan.id, 'http.response', responseMeta)
+      trace.metadata = { ...trace.metadata, response: responseMeta }
+
+      const completedSpan = tracer.endSpan(rootSpan.id)
+      if (completedSpan) {
+        vision.getTraceStore().addSpan(traceId, completedSpan)
+      }
+
+      vision.completeTrace(traceId, reply.statusCode, duration)
+
+      if (logging) {
+        console.info(
+          `INF request completed code=${reply.statusCode} duration=${duration}ms method=${request.method} path=${request.url} traceId=${traceId}`
+        )
+      }
+    } catch (error) {
+      console.error('Vision: Error completing trace:', error)
+    }
+  })
+}
+
+export const visionPlugin = fp(visionPluginImpl, {
+  fastify: '5.x',
+  name: '@getvision/adapter-fastify'
+})
+
+export function enableAutoDiscovery(
+  fastify: FastifyInstance,
+  options?: { services?: ServiceDefinition[] }
+): void {
+  const vision = visionInstance
+  if (!vision) {
+    console.warn('Vision not initialized. Call visionPlugin first.')
+    return
+  }
+
+  fastify.addHook('onReady', async () => {
+    const routes: RouteMetadata[] = []
+    const services: Record<string, { name: string; description?: string; routes: RouteMetadata[] }> = {}
+
+    // Use captured routes from onRoute hook
+    const CAPTURE_KEY = Symbol.for('vision.fastify.routes')
+    const capturedRoutes = (fastify as any)[CAPTURE_KEY] || []
+
+    for (const route of capturedRoutes) {
+      const routeMeta: RouteMetadata = {
+        method: route.method,
+        path: route.url,
+        handler: route.handlerName || 'anonymous',
+      }
+
+      // Try to get schema from route
+      if (route.schema?.body) {
+        try {
+          routeMeta.requestBody = jsonSchemaToTemplate(route.schema.body)
+        } catch (e) {
+          // Ignore schema conversion errors
+        }
+      }
+
+      // Try to get response schema (Fastify supports response: { 200: { ... } })
+      if (route.schema?.response) {
+        try {
+          // Get the success response schema (200, 201, etc.)
+          const responseSchema = route.schema.response['200'] || 
+                                 route.schema.response['201'] || 
+                                 route.schema.response['2xx']
+          if (responseSchema) {
+            routeMeta.responseBody = jsonSchemaToTemplate(responseSchema)
+          }
+        } catch (e) {
+          // Ignore schema conversion errors
+        }
+      }
+
+      routes.push(routeMeta)
+
+      // Group into services
+      const serviceName = findServiceForRoute(routeMeta.path, options?.services)
+      if (!services[serviceName]) {
+        services[serviceName] = {
+          name: serviceName,
+          routes: [],
+        }
+      }
+      services[serviceName].routes.push(routeMeta)
+    }
+
+    vision.registerRoutes(routes)
+    vision.registerServices(Object.values(services))
+
+    console.info(`Vision: Discovered ${routes.length} routes across ${Object.keys(services).length} services`)
+  })
+}
+
+function jsonSchemaToTemplate(schema: any): RequestBodySchema {
+  if (!schema || typeof schema !== 'object') {
+    return {
+      template: '{}',
+      fields: [],
+    }
+  }
+
+  const lines: string[] = ['{']
+  const fields: SchemaField[] = []
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    const props = Object.entries(schema.properties)
+    const required: string[] = Array.isArray(schema.required) ? schema.required : []
+
+    props.forEach(([key, prop]: [string, any], index) => {
+      const isRequired = required.includes(key)
+      const description = prop?.description || ''
+      const type = Array.isArray(prop?.type) ? prop.type[0] : prop?.type || 'any'
+
+      let value: string
+      switch (type) {
+        case 'string':
+          value = prop?.format === 'email' ? '"user@example.com"' : '"string"'
+          break
+        case 'number':
+        case 'integer':
+          value = '0'
+          break
+        case 'boolean':
+          value = 'false'
+          break
+        case 'array':
+          value = '[]'
+          break
+        case 'object':
+          value = '{}'
+          break
+        default:
+          value = 'null'
+      }
+
+      const comment = description
+        ? ` // ${description}${isRequired ? '' : ' (optional)'}`
+        : (isRequired ? '' : ' // optional')
+
+      const comma = index < props.length - 1 ? ',' : ''
+      lines.push(`  "${key}": ${value}${comma}${comment}`)
+
+      fields.push({
+        name: key,
+        type,
+        description: description || undefined,
+        required: isRequired,
+        example: prop?.examples?.[0],
+      })
+    })
+  }
+
+  lines.push('}')
+  return {
+    template: lines.join('\n'),
+    fields,
+  }
+}
+
+function findServiceForRoute(path: string, customServices?: ServiceDefinition[]): string {
+  if (customServices) {
+    for (const service of customServices) {
+      for (const pattern of service.routes) {
+        if (matchPattern(path, pattern)) {
+          return service.name
+        }
+      }
+    }
+  }
+
+  const segments = path.split('/').filter(Boolean)
+  if (segments.length === 0) return 'Root'
+
+  // Find first non-param segment
+  const firstSegment = segments.find(s => !s.startsWith(':')) || segments[0]
+  
+  // Skip param-only paths
+  if (firstSegment.startsWith(':')) return 'Root'
+  
+  return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1)
+}
+
+function matchPattern(path: string, pattern: string): boolean {
+  if (pattern.endsWith('/*')) {
+    const prefix = pattern.slice(0, -2)
+    return path === prefix || path.startsWith(prefix + '/')
+  }
+  return path === pattern
+}
+
+export { generateZodTemplate } from '@getvision/core'

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../packages/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2022"],
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/fastify.d.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}