@raystack/chronicle 0.5.3 → 0.5.4

package/dist/cli/index.js

@@ -256,7 +256,8 @@ var analyticsSchema = z.object({
 });
 var telemetrySchema = z.object({
   enabled: z.boolean().optional(),
-  serviceName: z.string().optional()
+  serviceName: z.string().optional(),
+  port: z.number().int().min(1).max(65535).default(9090)
 });
 var chronicleConfigSchema = z.object({
   title: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,7 +49,7 @@
     "codemirror": "^6.0.2",
     "commander": "^14.0.2",
     "fumadocs-core": "16.6.15",
-    "fumadocs-mdx": "^14.2.6",
+    "fumadocs-mdx": "14.2.6",
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",

package/src/lib/page-context.tsx

@@ -22,6 +22,7 @@ interface PageContextValue {
   config: ChronicleConfig;
   tree: Root;
   page: PageData | null;
+  errorStatus: number | null;
   apiSpecs: ApiSpec[];
 }
 
@@ -35,6 +36,7 @@ export function usePageContext(): PageContextValue {
       config: { title: 'Documentation' },
       tree: { name: 'root', children: [] } as Root,
       page: null,
+      errorStatus: null,
       apiSpecs: []
     };
   }
@@ -50,6 +52,16 @@ interface PageProviderProps {
   children: ReactNode;
 }
 
+function isApisRoute(pathname: string): boolean {
+  return pathname === '/apis' || pathname.startsWith('/apis/');
+}
+
+function getInitialErrorStatus(page: PageData | null, pathname: string): number | null {
+  if (page) return null;
+  if (pathname === '/' || isApisRoute(pathname)) return null;
+  return 404;
+}
+
 export function PageProvider({
   initialConfig,
   initialTree,
@@ -61,6 +73,7 @@ export function PageProvider({
   const { pathname } = useLocation();
   const [tree] = useState<Root>(initialTree);
   const [page, setPage] = useState<PageData | null>(initialPage);
+  const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, pathname));
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [currentPath, setCurrentPath] = useState(pathname);
 
@@ -70,7 +83,7 @@ export function PageProvider({
 
     const cancelled = { current: false };
 
-    if (pathname.startsWith('/apis')) {
+    if (isApisRoute(pathname)) {
       if (apiSpecs.length === 0) {
         fetch('/api/specs')
           .then(res => res.json())
@@ -86,24 +99,39 @@ export function PageProvider({
       ? []
       : pathname.slice(1).split('/').filter(Boolean);
 
-    const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
+    const apiPath = slug.length === 0 ? '/api/page' : `/api/page?slug=${slug.join(',')}`;
 
     fetch(apiPath)
-      .then(res => res.json())
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string }) => {
-        if (cancelled.current) return;
+      .then(res => {
+        if (!res.ok) {
+          if (!cancelled.current) {
+            setPage(null);
+            setErrorStatus(res.status);
+          }
+          return;
+        }
+        return res.json();
+      })
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string } | undefined) => {
+        if (cancelled.current || !data) return;
         const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
         if (cancelled.current) return;
+        setErrorStatus(null);
         setPage({ slug, frontmatter: data.frontmatter, content, toc });
       })
-      .catch(() => {});
+      .catch(() => {
+        if (!cancelled.current) {
+          setPage(null);
+          setErrorStatus(500);
+        }
+      });
 
     return () => { cancelled.current = true; };
   }, [pathname]);
 
   return (
     <PageContext.Provider
-      value={{ config: initialConfig, tree, page, apiSpecs }}
+      value={{ config: initialConfig, tree, page, errorStatus, apiSpecs }}
     >
       {children}
     </PageContext.Provider>

package/src/pages/DocsPage.tsx

@@ -1,5 +1,6 @@
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
 
 interface DocsPageProps {
@@ -7,8 +8,10 @@ interface DocsPageProps {
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page } = usePageContext();
+  const { config, tree, page, errorStatus } = usePageContext();
 
+  if (errorStatus === 404) return <NotFound />;
+  if (errorStatus) return <NotFound />;
   if (!page) return null;
 
   const { Page } = getTheme(config.theme?.name);

package/src/pages/NotFound.module.css

@@ -0,0 +1,3 @@
+.emptyState {
+  justify-content: center;
+}

package/src/pages/NotFound.tsx

@@ -1,17 +1,12 @@
-import { Flex, Headline, Text } from '@raystack/apsara';
+import { EmptyState } from '@raystack/apsara';
+import styles from './NotFound.module.css';
 
 export function NotFound() {
   return (
-    <Flex
-      direction='column'
-      align='center'
-      justify='center'
-      style={{ minHeight: '60vh' }}
-    >
-      <Headline size='large' as='h1'>
-        404
-      </Headline>
-      <Text size={3}>Page not found</Text>
-    </Flex>
+    <EmptyState
+      heading="404"
+      subHeading="Page not found"
+      classNames={{ container: styles.emptyState }}
+    />
   );
 }

package/src/server/api/{page/[...slug].ts → page.ts}

@@ -2,8 +2,8 @@ import { defineHandler, HTTPError } from 'nitro';
 import { getPage, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 
 export default defineHandler(async event => {
-  const slugParam = event.context.params?.slug ?? '';
-  const slug = slugParam ? slugParam.split('/') : [];
+  const slugParam = event.url.searchParams.get('slug') ?? '';
+  const slug = slugParam ? slugParam.split(',').filter(Boolean) : [];
   const page = await getPage(slug);
 
   if (!page) {

package/src/server/entry-server.tsx

@@ -9,8 +9,8 @@ import { loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { useNitroApp } from 'nitro/app';
 import { App } from './App';
-import { recordSSRRender } from './telemetry';
 
 import clientAssets from './entry-client?assets=client';
 import serverAssets from './entry-server?assets=ssr';
@@ -98,7 +98,7 @@ export default {
     const isApiRoute = pathname.startsWith('/apis');
     const status = !page && !isApiRoute && slug.length > 0 ? 404 : 200;
 
-    recordSSRRender(pathname, status, renderDuration);
+    useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, status, renderDuration);
 
     return new Response(stream, {
       status,

package/src/server/plugins/telemetry.ts

@@ -1,21 +1,61 @@
+import type { Counter, Histogram } from '@opentelemetry/api'
+import { MeterProvider } from '@opentelemetry/sdk-metrics'
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
+import type { H3Event } from 'h3'
 import { definePlugin } from 'nitro'
 import { loadConfig } from '@/lib/config'
-import { initTelemetry, recordRequest } from '../telemetry'
+
+declare module 'nitro/types' {
+  interface NitroRuntimeHooks {
+    'chronicle:ssr-rendered': (route: string, status: number, durationMs: number) => void
+  }
+}
 
 export default definePlugin((nitroApp) => {
   const config = loadConfig()
   if (!config.telemetry?.enabled) return
 
-  initTelemetry(config)
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: config.telemetry?.serviceName ?? 'chronicle',
+  })
+
+  const port = config.telemetry?.port ?? 9090
+  const exporter = new PrometheusExporter({ port })
+  const provider = new MeterProvider({ resource, readers: [exporter] })
+  const meter = provider.getMeter('chronicle')
+
+  const requestCounter: Counter = meter.createCounter('http_server_request_total', {
+    description: 'Total HTTP requests',
+  })
+  const requestDuration: Histogram = meter.createHistogram('http_server_request_duration_ms', {
+    description: 'HTTP request duration in ms',
+  })
+  const ssrRenderDuration: Histogram = meter.createHistogram('http_server_ssr_render_duration_ms', {
+    description: 'SSR render duration in ms',
+  })
+
+  nitroApp.hooks.hook('close', async () => {
+    await provider.shutdown()
+    await exporter.shutdown()
+  })
+
+  nitroApp.hooks.hook('chronicle:ssr-rendered', (route, status, durationMs) => {
+    ssrRenderDuration.record(durationMs, { route, status })
+  })
 
   nitroApp.hooks.hook('request', (event) => {
-    if (event.path === '/api/metrics') return
-    event.context._requestStart = performance.now()
+    (event as H3Event).context._requestStart = performance.now()
   })
 
   nitroApp.hooks.hook('response', (res, event) => {
-    if (!event.context._requestStart) return
-    const duration = performance.now() - event.context._requestStart
-    recordRequest(event.method, event.path, res.status, duration)
+    const start = (event as H3Event).context._requestStart as number | undefined
+    if (start === undefined) return
+    const duration = performance.now() - start
+    const method = event.req.method
+    const route = new URL(event.req.url).pathname
+    requestCounter.add(1, { method, route, status: res.status })
+    requestDuration.record(duration, { method, route, status: res.status })
   })
 })

package/src/types/config.ts

@@ -70,6 +70,7 @@ const analyticsSchema = z.object({
 const telemetrySchema = z.object({
   enabled: z.boolean().optional(),
   serviceName: z.string().optional(),
+  port: z.number().int().min(1).max(65535).default(9090),
 })
 
 export const chronicleConfigSchema = z.object({

package/src/server/api/metrics.ts

@@ -1,23 +0,0 @@
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import { defineHandler } from 'nitro'
-import { getExporter } from '../telemetry'
-
-export default defineHandler(async () => {
-  const exporter = getExporter()
-  if (!exporter) {
-    return new Response('Telemetry not enabled', { status: 404 })
-  }
-
-  const metricsString = await new Promise<string>((resolve) => {
-    const mockRes = {
-      setHeader: () => mockRes,
-      end: (data: string) => resolve(data),
-    } as unknown as ServerResponse
-
-    exporter.getMetricsRequestHandler({} as unknown as IncomingMessage, mockRes)
-  })
-
-  return new Response(metricsString, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  })
-})

package/src/server/api/page/index.ts

@@ -1 +0,0 @@
-export { default } from './[...slug]';

package/src/server/telemetry.ts

@@ -1,49 +0,0 @@
-import type { Counter, Histogram } from '@opentelemetry/api'
-import sdkMetrics from '@opentelemetry/sdk-metrics'
-import prometheusExporter from '@opentelemetry/exporter-prometheus'
-import resources from '@opentelemetry/resources'
-import semconv from '@opentelemetry/semantic-conventions'
-import type { ChronicleConfig } from '@/types/config'
-
-const { MeterProvider } = sdkMetrics
-const { PrometheusExporter } = prometheusExporter
-const { resourceFromAttributes } = resources
-const { ATTR_SERVICE_NAME } = semconv
-
-let exporter: PrometheusExporter
-let requestCounter: Counter
-let requestDuration: Histogram
-let ssrRenderDuration: Histogram
-
-export function initTelemetry(config: ChronicleConfig) {
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: config.telemetry?.serviceName ?? 'chronicle',
-  })
-
-  exporter = new PrometheusExporter({ preventServerStart: true })
-  const provider = new MeterProvider({ resource, readers: [exporter] })
-  const meter = provider.getMeter('chronicle')
-
-  requestCounter = meter.createCounter('http_server_request_total', {
-    description: 'Total HTTP requests',
-  })
-  requestDuration = meter.createHistogram('http_server_request_duration_ms', {
-    description: 'HTTP request duration in ms',
-  })
-  ssrRenderDuration = meter.createHistogram('http_server_ssr_render_duration_ms', {
-    description: 'SSR render duration in ms',
-  })
-}
-
-export function getExporter() {
-  return exporter
-}
-
-export function recordRequest(method: string, route: string, status: number, durationMs: number) {
-  requestCounter?.add(1, { method, route, status })
-  requestDuration?.record(durationMs, { method, route, status })
-}
-
-export function recordSSRRender(route: string, status: number, durationMs: number) {
-  ssrRenderDuration?.record(durationMs, { route, status })
-}