@geekmidas/telescope 0.0.1

package/src/server/__tests__/hono.spec.ts

@@ -0,0 +1,340 @@
+import { Hono } from 'hono';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Telescope } from '../../Telescope';
+import { InMemoryStorage } from '../../storage/memory';
+import { createMiddleware, createUI, getRequestId } from '../hono';
+
+describe('Hono Adapter', () => {
+  let telescope: Telescope;
+  let storage: InMemoryStorage;
+
+  beforeEach(() => {
+    storage = new InMemoryStorage();
+    telescope = new Telescope({ storage });
+  });
+
+  afterEach(() => {
+    telescope.destroy();
+  });
+
+  describe('createMiddleware', () => {
+    it('should capture GET requests', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/users', (c) => c.json({ users: [] }));
+
+      const res = await app.request('/api/users');
+
+      expect(res.status).toBe(200);
+
+      const requests = await telescope.getRequests();
+      expect(requests).toHaveLength(1);
+      expect(requests[0].method).toBe('GET');
+      expect(requests[0].path).toBe('/api/users');
+      expect(requests[0].status).toBe(200);
+    });
+
+    it('should capture POST requests with body', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.post('/api/users', async (c) => {
+        const body = await c.req.json();
+        return c.json({ id: '123', ...body }, 201);
+      });
+
+      const res = await app.request('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'John' }),
+      });
+
+      expect(res.status).toBe(201);
+
+      const requests = await telescope.getRequests();
+      expect(requests).toHaveLength(1);
+      expect(requests[0].method).toBe('POST');
+      expect(requests[0].body).toEqual({ name: 'John' });
+      expect(requests[0].status).toBe(201);
+    });
+
+    it('should capture query parameters', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/search', (c) => c.json({ query: c.req.query('q') }));
+
+      await app.request('/api/search?q=test&limit=10');
+
+      const requests = await telescope.getRequests();
+      expect(requests[0].query).toEqual({ q: 'test', limit: '10' });
+    });
+
+    it('should capture request headers', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/test', (c) => c.json({ ok: true }));
+
+      await app.request('/api/test', {
+        headers: {
+          Authorization: 'Bearer token123',
+          'X-Custom-Header': 'custom-value',
+        },
+      });
+
+      const requests = await telescope.getRequests();
+      expect(requests[0].headers['authorization']).toBe('Bearer token123');
+      expect(requests[0].headers['x-custom-header']).toBe('custom-value');
+    });
+
+    it('should capture response duration', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/slow', async (c) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return c.json({ ok: true });
+      });
+
+      await app.request('/api/slow');
+
+      const requests = await telescope.getRequests();
+      expect(requests[0].duration).toBeGreaterThan(40);
+    });
+
+    it('should handle errors thrown in handlers', async () => {
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/error', () => {
+        throw new Error('Test error');
+      });
+
+      // Hono catches errors and returns 500
+      const res = await app.request('/api/error');
+      expect(res.status).toBe(500);
+
+      // The error is logged to stderr but the request still completes
+      // Exception recording depends on Hono's error handling behavior
+    });
+
+    it('should skip ignored paths', async () => {
+      const ignoredTelescope = new Telescope({
+        storage,
+        ignorePatterns: ['/health', '/__telescope/*'],
+      });
+
+      const app = new Hono();
+      app.use('*', createMiddleware(ignoredTelescope));
+      app.get('/health', (c) => c.json({ status: 'ok' }));
+      app.get('/api/users', (c) => c.json({ users: [] }));
+
+      await app.request('/health');
+      await app.request('/api/users');
+
+      const requests = await ignoredTelescope.getRequests();
+      expect(requests).toHaveLength(1);
+      expect(requests[0].path).toBe('/api/users');
+
+      ignoredTelescope.destroy();
+    });
+
+    it('should skip when telescope is disabled', async () => {
+      const disabled = new Telescope({ storage, enabled: false });
+
+      const app = new Hono();
+      app.use('*', createMiddleware(disabled));
+      app.get('/api/test', (c) => c.json({ ok: true }));
+
+      await app.request('/api/test');
+
+      const requests = await storage.getRequests();
+      expect(requests).toHaveLength(0);
+
+      disabled.destroy();
+    });
+
+    it('should not record body when recordBody is false', async () => {
+      const noBody = new Telescope({ storage, recordBody: false });
+
+      const app = new Hono();
+      app.use('*', createMiddleware(noBody));
+      app.post('/api/users', async (c) => {
+        await c.req.json();
+        return c.json({ id: '123' });
+      });
+
+      await app.request('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'John' }),
+      });
+
+      const requests = await noBody.getRequests();
+      expect(requests[0].body).toBeUndefined();
+
+      noBody.destroy();
+    });
+  });
+
+  describe('createUI', () => {
+    it('should return requests list', async () => {
+      // Add a request first
+      await telescope.recordRequest({
+        method: 'GET',
+        path: '/api/test',
+        url: 'http://localhost/api/test',
+        headers: {},
+        query: {},
+        status: 200,
+        responseHeaders: {},
+        duration: 10,
+      });
+
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/requests');
+      const data = await res.json();
+
+      expect(Array.isArray(data)).toBe(true);
+      expect(data).toHaveLength(1);
+    });
+
+    it('should return single request by ID', async () => {
+      const requestId = await telescope.recordRequest({
+        method: 'GET',
+        path: '/api/test',
+        url: 'http://localhost/api/test',
+        headers: {},
+        query: {},
+        status: 200,
+        responseHeaders: {},
+        duration: 10,
+      });
+
+      const ui = createUI(telescope);
+      const res = await ui.request(`/api/requests/${requestId}`);
+      const data = await res.json();
+
+      expect(data.id).toBe(requestId);
+      expect(data.path).toBe('/api/test');
+    });
+
+    it('should return 404 for non-existent request', async () => {
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/requests/non-existent');
+
+      expect(res.status).toBe(404);
+    });
+
+    it('should return exceptions list', async () => {
+      await telescope.exception(new Error('Test error'));
+
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/exceptions');
+      const data = await res.json();
+
+      expect(Array.isArray(data)).toBe(true);
+      expect(data).toHaveLength(1);
+      expect(data[0].message).toBe('Test error');
+    });
+
+    it('should return logs list', async () => {
+      await telescope.info('Test log', { key: 'value' });
+
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/logs');
+      const data = await res.json();
+
+      expect(Array.isArray(data)).toBe(true);
+      expect(data).toHaveLength(1);
+      expect(data[0].message).toBe('Test log');
+    });
+
+    it('should return stats', async () => {
+      await telescope.recordRequest({
+        method: 'GET',
+        path: '/test',
+        url: 'http://localhost/test',
+        headers: {},
+        query: {},
+        status: 200,
+        responseHeaders: {},
+        duration: 10,
+      });
+      await telescope.info('Test');
+      await telescope.exception(new Error('Test'));
+
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/stats');
+      const data = await res.json();
+
+      expect(data.requests).toBe(1);
+      expect(data.logs).toBe(1);
+      expect(data.exceptions).toBe(1);
+    });
+
+    it('should return dashboard HTML on root', async () => {
+      const ui = createUI(telescope);
+      const res = await ui.request('/');
+
+      expect(res.headers.get('content-type')).toContain('text/html');
+      const html = await res.text();
+      expect(html).toContain('<!DOCTYPE html>');
+    });
+
+    it('should support pagination query params', async () => {
+      for (let i = 0; i < 10; i++) {
+        await telescope.recordRequest({
+          method: 'GET',
+          path: `/api/item/${i}`,
+          url: `http://localhost/api/item/${i}`,
+          headers: {},
+          query: {},
+          status: 200,
+          responseHeaders: {},
+          duration: 10,
+        });
+      }
+
+      const ui = createUI(telescope);
+      const res = await ui.request('/api/requests?limit=3&offset=0');
+      const data = await res.json();
+
+      expect(data).toHaveLength(3);
+    });
+  });
+
+  describe('getRequestId', () => {
+    it('should return undefined during handler (ID is set after response)', async () => {
+      let capturedRequestId: string | undefined;
+
+      const app = new Hono();
+      app.use('*', createMiddleware(telescope));
+      app.get('/api/test', (c) => {
+        // Note: The request ID is set AFTER next() completes,
+        // so it's not available during the handler execution
+        capturedRequestId = getRequestId(c);
+        return c.json({ ok: true });
+      });
+
+      await app.request('/api/test');
+
+      // The ID is not available during handler execution
+      expect(capturedRequestId).toBeUndefined();
+
+      // But the request was still recorded
+      const requests = await telescope.getRequests();
+      expect(requests).toHaveLength(1);
+    });
+
+    it('should return undefined when middleware not used', async () => {
+      let capturedRequestId: string | undefined;
+
+      const app = new Hono();
+      app.get('/api/test', (c) => {
+        capturedRequestId = getRequestId(c);
+        return c.json({ ok: true });
+      });
+
+      await app.request('/api/test');
+
+      expect(capturedRequestId).toBeUndefined();
+    });
+  });
+});

package/src/server/hono.ts

@@ -0,0 +1,247 @@
+import { Hono } from 'hono';
+import type { Context, MiddlewareHandler, Next } from 'hono';
+import type { Telescope } from '../Telescope';
+import type { QueryOptions } from '../types';
+import { getAsset, getIndexHtml } from '../ui-assets';
+
+const CONTEXT_KEY = 'telescope-request-id';
+
+/**
+ * Create Hono middleware that captures requests and responses
+ */
+export function createMiddleware(telescope: Telescope): MiddlewareHandler {
+  return async (c: Context, next: Next) => {
+    if (!telescope.enabled) {
+      return next();
+    }
+
+    if (telescope.shouldIgnore(c.req.path)) {
+      return next();
+    }
+
+    const startTime = performance.now();
+
+    // Capture request data
+    const headers: Record<string, string> = {};
+    c.req.raw.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    const url = new URL(c.req.url);
+    const query: Record<string, string> = {};
+    url.searchParams.forEach((value, key) => {
+      query[key] = value;
+    });
+
+    let body: unknown;
+    if (
+      telescope.recordBody &&
+      ['POST', 'PUT', 'PATCH'].includes(c.req.method)
+    ) {
+      try {
+        const contentType = c.req.header('content-type') || '';
+        if (contentType.includes('application/json')) {
+          body = await c.req.json();
+        } else if (contentType.includes('application/x-www-form-urlencoded')) {
+          const formData = await c.req.formData();
+          body = Object.fromEntries(formData.entries());
+        } else if (contentType.includes('text/')) {
+          body = await c.req.text();
+        }
+      } catch {
+        // Ignore body parsing errors
+      }
+    }
+
+    const ip = c.req.header('x-forwarded-for') || c.req.header('x-real-ip');
+
+    try {
+      await next();
+
+      // Capture response data
+      const duration = performance.now() - startTime;
+
+      const responseHeaders: Record<string, string> = {};
+      c.res.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+
+      let responseBody: unknown;
+      if (telescope.recordBody) {
+        try {
+          const contentType = c.res.headers.get('content-type') || '';
+          if (contentType.includes('application/json')) {
+            const cloned = c.res.clone();
+            responseBody = await cloned.json();
+          }
+        } catch {
+          // Ignore body parsing errors
+        }
+      }
+
+      const requestId = await telescope.recordRequest({
+        method: c.req.method,
+        path: c.req.path,
+        url: c.req.url,
+        headers,
+        body,
+        query,
+        status: c.res.status,
+        responseHeaders,
+        responseBody,
+        duration,
+        ip,
+      });
+
+      c.set(CONTEXT_KEY, requestId);
+    } catch (error) {
+      await telescope.exception(error as Error);
+      throw error;
+    }
+  };
+}
+
+/**
+ * Parse query options from Hono context
+ */
+function parseQueryOptions(c: Context): QueryOptions {
+  const limit = parseInt(c.req.query('limit') || '50', 10);
+  const offset = parseInt(c.req.query('offset') || '0', 10);
+  const search = c.req.query('search');
+  const before = c.req.query('before');
+  const after = c.req.query('after');
+  const tags = c.req.query('tags')?.split(',').filter(Boolean);
+
+  return {
+    limit: Math.min(limit, 100),
+    offset,
+    search,
+    before: before ? new Date(before) : undefined,
+    after: after ? new Date(after) : undefined,
+    tags,
+  };
+}
+
+/**
+ * Create Hono app with dashboard UI and API routes
+ */
+export function createUI(telescope: Telescope): Hono {
+  const app = new Hono();
+
+  // API routes
+  app.get('/api/requests', async (c) => {
+    const options = parseQueryOptions(c);
+    const requests = await telescope.getRequests(options);
+    return c.json(requests);
+  });
+
+  app.get('/api/requests/:id', async (c) => {
+    const request = await telescope.getRequest(c.req.param('id'));
+    if (!request) {
+      return c.json({ error: 'Request not found' }, 404);
+    }
+    return c.json(request);
+  });
+
+  app.get('/api/exceptions', async (c) => {
+    const options = parseQueryOptions(c);
+    const exceptions = await telescope.getExceptions(options);
+    return c.json(exceptions);
+  });
+
+  app.get('/api/exceptions/:id', async (c) => {
+    const exception = await telescope.getException(c.req.param('id'));
+    if (!exception) {
+      return c.json({ error: 'Exception not found' }, 404);
+    }
+    return c.json(exception);
+  });
+
+  app.get('/api/logs', async (c) => {
+    const options = parseQueryOptions(c);
+    const logs = await telescope.getLogs(options);
+    return c.json(logs);
+  });
+
+  app.get('/api/stats', async (c) => {
+    const stats = await telescope.getStats();
+    return c.json(stats);
+  });
+
+  // Static assets
+  app.get('/assets/:filename', (c) => {
+    const filename = c.req.param('filename');
+    const assetPath = `assets/${filename}`;
+    const asset = getAsset(assetPath);
+    if (asset) {
+      return c.body(asset.content, 200, {
+        'Content-Type': asset.contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      });
+    }
+    return c.notFound();
+  });
+
+  // Dashboard UI - serve React app
+  app.get('/', (c) => {
+    const html = getIndexHtml();
+    if (html) {
+      return c.html(html);
+    }
+    // Fallback to inline HTML if UI assets not available
+    return c.html(telescope.getDashboardHtml());
+  });
+
+  app.get('/*', (c) => {
+    // SPA fallback - serve index.html for client-side routing
+    const html = getIndexHtml();
+    if (html) {
+      return c.html(html);
+    }
+    return c.html(telescope.getDashboardHtml());
+  });
+
+  return app;
+}
+
+/**
+ * Set up WebSocket routes for real-time updates.
+ * Requires @hono/node-ws for Node.js or Bun's built-in WebSocket.
+ */
+export function setupWebSocket(
+  app: Hono,
+  telescope: Telescope,
+  upgradeWebSocket: (handler: any) => any,
+): void {
+  app.get(
+    '/ws',
+    upgradeWebSocket(() => ({
+      onOpen: (_event: Event, ws: WebSocket) => {
+        telescope.addWsClient(ws);
+      },
+      onClose: (_event: Event, ws: WebSocket) => {
+        telescope.removeWsClient(ws);
+      },
+      onMessage: (event: MessageEvent, ws: WebSocket) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === 'ping') {
+            ws.send(JSON.stringify({ type: 'pong' }));
+          }
+        } catch {
+          // Ignore invalid messages
+        }
+      },
+    })),
+  );
+}
+
+/**
+ * Get the request ID from Hono context (set by middleware)
+ */
+export function getRequestId(c: Context): string | undefined {
+  return c.get(CONTEXT_KEY);
+}
+
+// Re-export types
+export type { Telescope };