@pyreon/zero 0.1.1 → 0.3.0

package/src/api-routes.ts

@@ -0,0 +1,233 @@
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** HTTP methods supported by API routes. */
+export type HttpMethod =
+  | 'GET'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'HEAD'
+  | 'OPTIONS'
+
+/** Context passed to API route handlers. */
+export interface ApiContext {
+  /** The incoming request. */
+  request: Request
+  /** Parsed URL. */
+  url: URL
+  /** URL path. */
+  path: string
+  /** Dynamic route parameters (e.g., { id: "123" }). */
+  params: Record<string, string>
+  /** Request headers. */
+  headers: Headers
+}
+
+/** An API route handler function. */
+export type ApiHandler = (ctx: ApiContext) => Response | Promise<Response>
+
+/** An API route module — exports named HTTP method handlers. */
+export interface ApiRouteModule {
+  GET?: ApiHandler
+  POST?: ApiHandler
+  PUT?: ApiHandler
+  PATCH?: ApiHandler
+  DELETE?: ApiHandler
+  HEAD?: ApiHandler
+  OPTIONS?: ApiHandler
+}
+
+/** A registered API route entry. */
+export interface ApiRouteEntry {
+  /** URL pattern (e.g., "/api/posts/:id"). */
+  pattern: string
+  /** The route module with method handlers. */
+  module: ApiRouteModule
+}
+
+// ─── Pattern matching ────────────────────────────────────────────────────────
+
+/**
+ * Match a URL path against an API route pattern.
+ * Returns extracted params or null if no match.
+ */
+export function matchApiRoute(
+  pattern: string,
+  path: string,
+): Record<string, string> | null {
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = path.split('/').filter(Boolean)
+  const params: Record<string, string> = {}
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i]
+
+    // Catch-all: :param*
+    if (pp.endsWith('*')) {
+      const paramName = pp.slice(1, -1)
+      params[paramName] = pathParts.slice(i).join('/')
+      return params
+    }
+
+    // No more path segments
+    if (i >= pathParts.length) return null
+
+    // Dynamic segment: :param
+    if (pp.startsWith(':')) {
+      params[pp.slice(1)] = pathParts[i]
+      continue
+    }
+
+    // Static segment
+    if (pp !== pathParts[i]) return null
+  }
+
+  return patternParts.length === pathParts.length ? params : null
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+const HTTP_METHODS: HttpMethod[] = [
+  'GET',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'HEAD',
+  'OPTIONS',
+]
+
+/**
+ * Create a middleware that dispatches API route requests.
+ * API routes are matched by URL pattern and HTTP method.
+ */
+export function createApiMiddleware(routes: ApiRouteEntry[]): Middleware {
+  return async (ctx: MiddlewareContext) => {
+    for (const route of routes) {
+      const params = matchApiRoute(route.pattern, ctx.path)
+      if (!params) continue
+
+      const method = ctx.req.method.toUpperCase() as HttpMethod
+      const handler = route.module[method]
+
+      if (!handler) {
+        // Route matched but method not supported
+        const allowed = HTTP_METHODS.filter((m) => route.module[m]).join(', ')
+        return new Response(null, {
+          status: 405,
+          headers: {
+            Allow: allowed,
+            'Content-Type': 'application/json',
+          },
+        })
+      }
+
+      return handler({
+        request: ctx.req,
+        url: ctx.url,
+        path: ctx.path,
+        params,
+        headers: ctx.req.headers,
+      })
+    }
+  }
+}
+
+// ─── Virtual module generation ───────────────────────────────────────────────
+
+/**
+ * Detect whether a route file is an API route.
+ * API routes are `.ts` or `.js` files inside an `api/` directory.
+ */
+export function isApiRoute(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, '/')
+  return (
+    normalized.startsWith('api/') &&
+    (normalized.endsWith('.ts') || normalized.endsWith('.js')) &&
+    !normalized.endsWith('.tsx') &&
+    !normalized.endsWith('.jsx')
+  )
+}
+
+/**
+ * Convert an API route file path to a URL pattern.
+ *
+ * Examples:
+ *   "api/posts.ts"        → "/api/posts"
+ *   "api/posts/index.ts"  → "/api/posts"
+ *   "api/posts/[id].ts"   → "/api/posts/:id"
+ *   "api/[...path].ts"    → "/api/:path*"
+ */
+export function apiFilePathToPattern(filePath: string): string {
+  let route = filePath
+  // Remove extension
+  for (const ext of ['.ts', '.js']) {
+    if (route.endsWith(ext)) {
+      route = route.slice(0, -ext.length)
+      break
+    }
+  }
+
+  const segments = route.split('/')
+  const urlSegments: string[] = []
+
+  for (const seg of segments) {
+    if (seg === 'index') continue
+
+    // Catch-all: [...param]
+    const catchAll = seg.match(/^\[\.\.\.(\w+)\]$/)
+    if (catchAll) {
+      urlSegments.push(`:${catchAll[1]}*`)
+      continue
+    }
+
+    // Dynamic: [param]
+    const dynamic = seg.match(/^\[(\w+)\]$/)
+    if (dynamic) {
+      urlSegments.push(`:${dynamic[1]}`)
+      continue
+    }
+
+    urlSegments.push(seg)
+  }
+
+  return `/${urlSegments.join('/')}`
+}
+
+/**
+ * Generate a virtual module that exports API route entries.
+ * Each entry maps a URL pattern to a module with HTTP method handlers.
+ */
+export function generateApiRouteModule(
+  files: string[],
+  routesDir: string,
+): string {
+  const apiFiles = files.filter(isApiRoute)
+
+  if (apiFiles.length === 0) {
+    return 'export const apiRoutes = []\n'
+  }
+
+  const imports: string[] = []
+  const entries: string[] = []
+
+  for (let i = 0; i < apiFiles.length; i++) {
+    const name = `_api${i}`
+    const fullPath = `${routesDir}/${apiFiles[i]}`
+    const pattern = apiFilePathToPattern(apiFiles[i])
+
+    imports.push(`import * as ${name} from "${fullPath}"`)
+    entries.push(`  { pattern: ${JSON.stringify(pattern)}, module: ${name} }`)
+  }
+
+  return [
+    ...imports,
+    '',
+    'export const apiRoutes = [',
+    entries.join(',\n'),
+    ']',
+  ].join('\n')
+}

package/src/compression.ts

@@ -0,0 +1,107 @@
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+
+// ─── Compression middleware ─────────────────────────────────────────────────
+
+export interface CompressionConfig {
+  /** Minimum response size in bytes to compress. Default: `1024` (1KB) */
+  threshold?: number
+  /** Encoding preference order. Default: `["gzip", "deflate"]` */
+  encodings?: ('gzip' | 'deflate')[]
+}
+
+/**
+ * Compression middleware — compresses responses using gzip or deflate
+ * based on the client's Accept-Encoding header.
+ *
+ * Only compresses text-based content types (HTML, JSON, JS, CSS, XML, SVG).
+ * Skips responses below the size threshold and already-encoded responses.
+ *
+ * @example
+ * import { compressionMiddleware } from "@pyreon/zero/compression"
+ *
+ * compressionMiddleware() // gzip with 1KB threshold
+ * compressionMiddleware({ threshold: 512, encodings: ["gzip"] })
+ */
+export function compressionMiddleware(
+  config: CompressionConfig = {},
+): Middleware {
+  const { threshold = 1024, encodings = ['gzip', 'deflate'] } = config
+
+  return (ctx: MiddlewareContext) => {
+    const acceptEncoding = ctx.req.headers.get('accept-encoding') ?? ''
+
+    // Find the best supported encoding
+    const encoding = encodings.find((enc) => acceptEncoding.includes(enc))
+    if (!encoding) return
+
+    // Store the encoding choice for post-processing
+    ctx.locals.__compressionEncoding = encoding
+    ctx.locals.__compressionThreshold = threshold
+    ctx.headers.append('Vary', 'Accept-Encoding')
+  }
+}
+
+/**
+ * Compress a Response body if it meets the criteria.
+ * Use this to post-process responses after the handler runs.
+ *
+ * @example
+ * const response = await handler(request)
+ * const compressed = await compressResponse(response, 'gzip', 1024)
+ */
+export async function compressResponse(
+  response: Response,
+  encoding: 'gzip' | 'deflate',
+  threshold: number,
+): Promise<Response> {
+  const contentType = response.headers.get('content-type') ?? ''
+
+  // Only compress text-based content
+  if (!isCompressible(contentType)) return response
+
+  // Skip if already encoded
+  if (response.headers.get('content-encoding')) return response
+
+  const body = await response.arrayBuffer()
+
+  // Skip below threshold
+  if (body.byteLength < threshold) return response
+
+  const compressed = await compress(body, encoding)
+
+  const headers = new Headers(response.headers)
+  headers.set('Content-Encoding', encoding)
+  headers.delete('Content-Length')
+  headers.append('Vary', 'Accept-Encoding')
+
+  return new Response(compressed, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
+
+const COMPRESSIBLE_TYPES = [
+  'text/',
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/xhtml+xml',
+  'image/svg+xml',
+]
+
+/** Check if a content type is compressible. Exported for testing. */
+export function isCompressible(contentType: string): boolean {
+  return COMPRESSIBLE_TYPES.some((t) => contentType.includes(t))
+}
+
+async function compress(
+  data: ArrayBuffer,
+  encoding: 'gzip' | 'deflate',
+): Promise<ArrayBuffer> {
+  const format = encoding === 'gzip' ? 'gzip' : 'deflate'
+  const stream = new Blob([data])
+    .stream()
+    .pipeThrough(new CompressionStream(format))
+  return new Response(stream).arrayBuffer()
+}

package/src/cors.ts

@@ -0,0 +1,102 @@
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+
+// ─── CORS middleware ────────────────────────────────────────────────────────
+
+export interface CorsConfig {
+  /** Allowed origins. Use `"*"` for any origin. Default: `"*"` */
+  origin?: string | string[] | ((origin: string) => boolean)
+  /** Allowed HTTP methods. Default: `["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]` */
+  methods?: string[]
+  /** Allowed request headers. Default: `["Content-Type", "Authorization"]` */
+  allowedHeaders?: string[]
+  /** Headers exposed to the client. Default: `[]` */
+  exposedHeaders?: string[]
+  /** Allow credentials (cookies, auth headers). Default: `false` */
+  credentials?: boolean
+  /** Preflight cache duration in seconds. Default: `86400` (24 hours) */
+  maxAge?: number
+}
+
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+const DEFAULT_HEADERS = ['Content-Type', 'Authorization']
+
+/**
+ * CORS middleware — handles preflight requests and sets appropriate
+ * Access-Control headers on all responses.
+ *
+ * @example
+ * import { corsMiddleware } from "@pyreon/zero/cors"
+ *
+ * corsMiddleware({ origin: "https://example.com", credentials: true })
+ *
+ * // Allow any origin
+ * corsMiddleware({ origin: "*" })
+ *
+ * // Multiple origins
+ * corsMiddleware({ origin: ["https://app.com", "https://admin.com"] })
+ */
+export function corsMiddleware(config: CorsConfig = {}): Middleware {
+  const {
+    origin = '*',
+    methods = DEFAULT_METHODS,
+    allowedHeaders = DEFAULT_HEADERS,
+    exposedHeaders = [],
+    credentials = false,
+    maxAge = 86400,
+  } = config
+
+  return (ctx: MiddlewareContext) => {
+    const requestOrigin = ctx.req.headers.get('origin') ?? ''
+    const resolvedOrigin = resolveOrigin(origin, requestOrigin)
+
+    if (!resolvedOrigin) return
+
+    // Set CORS headers on all responses
+    ctx.headers.set('Access-Control-Allow-Origin', resolvedOrigin)
+    if (credentials) {
+      ctx.headers.set('Access-Control-Allow-Credentials', 'true')
+    }
+    if (exposedHeaders.length > 0) {
+      ctx.headers.set(
+        'Access-Control-Expose-Headers',
+        exposedHeaders.join(', '),
+      )
+    }
+    if (resolvedOrigin !== '*') {
+      ctx.headers.append('Vary', 'Origin')
+    }
+
+    // Handle preflight
+    if (ctx.req.method === 'OPTIONS') {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          'Access-Control-Allow-Origin': resolvedOrigin,
+          'Access-Control-Allow-Methods': methods.join(', '),
+          'Access-Control-Allow-Headers': allowedHeaders.join(', '),
+          'Access-Control-Max-Age': String(maxAge),
+          ...(credentials
+            ? { 'Access-Control-Allow-Credentials': 'true' }
+            : {}),
+        },
+      })
+    }
+  }
+}
+
+function resolveOrigin(
+  config: CorsConfig['origin'],
+  requestOrigin: string,
+): string | null {
+  if (config === '*') return '*'
+  if (typeof config === 'string') {
+    return config === requestOrigin ? config : null
+  }
+  if (typeof config === 'function') {
+    return config(requestOrigin) ? requestOrigin : null
+  }
+  if (Array.isArray(config)) {
+    return config.includes(requestOrigin) ? requestOrigin : null
+  }
+  return null
+}

package/src/entry-server.ts

@@ -1,8 +1,10 @@
 import type { RouteRecord } from '@pyreon/router'
-import type { Middleware } from '@pyreon/server'
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
 import { createHandler } from '@pyreon/server'
+import type { ApiRouteEntry } from './api-routes'
+import { createApiMiddleware } from './api-routes'
 import { createApp } from './app'
-import type { ZeroConfig } from './types'
+import type { RouteMiddlewareEntry, ZeroConfig } from './types'
 
 // ─── Server entry factory ───────────────────────────────────────────────────
 
@@ -13,27 +15,80 @@ export interface CreateServerOptions {
   config?: ZeroConfig
   /** Additional middleware. */
   middleware?: Middleware[]
+  /** Per-route middleware from virtual:zero/route-middleware. */
+  routeMiddleware?: RouteMiddlewareEntry[]
+  /** API route entries from virtual:zero/api-routes. */
+  apiRoutes?: ApiRouteEntry[]
   /** HTML template override. */
   template?: string
   /** Client entry path. */
   clientEntry?: string
 }
 
+/**
+ * Create a middleware that dispatches per-route middleware based on URL pattern matching.
+ */
+function createRouteMiddlewareDispatcher(
+  entries: RouteMiddlewareEntry[],
+): Middleware {
+  return async (ctx: MiddlewareContext) => {
+    for (const entry of entries) {
+      if (matchPattern(entry.pattern, ctx.path)) {
+        const mw = Array.isArray(entry.middleware)
+          ? entry.middleware
+          : [entry.middleware]
+        for (const fn of mw) {
+          const result = await fn(ctx)
+          if (result) return result
+        }
+      }
+    }
+  }
+}
+
+/** Simple URL pattern matcher supporting :param and :param* segments. */
+export function matchPattern(pattern: string, path: string): boolean {
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = path.split('/').filter(Boolean)
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const pp = patternParts[i]
+    if (pp.endsWith('*')) return true // catch-all matches everything after
+    if (pp.startsWith(':')) continue // dynamic segment matches anything
+    if (pp !== pathParts[i]) return false
+  }
+
+  return patternParts.length === pathParts.length
+}
+
 /**
  * Create the SSR request handler for production.
  *
  * @example
  * import { routes } from "virtual:zero/routes"
+ * import { routeMiddleware } from "virtual:zero/route-middleware"
  * import { createServer } from "@pyreon/zero"
  *
- * export default createServer({ routes })
+ * export default createServer({ routes, routeMiddleware, apiRoutes })
  */
 export function createServer(options: CreateServerOptions) {
   const config = options.config ?? {}
-  const allMiddleware = [
-    ...(config.middleware ?? []),
-    ...(options.middleware ?? []),
-  ]
+
+  const allMiddleware: Middleware[] = []
+
+  // API routes run first — they short-circuit before SSR
+  if (options.apiRoutes?.length) {
+    allMiddleware.push(createApiMiddleware(options.apiRoutes))
+  }
+
+  // Per-route middleware runs next
+  if (options.routeMiddleware?.length) {
+    allMiddleware.push(createRouteMiddlewareDispatcher(options.routeMiddleware))
+  }
+
+  // Then global middleware from config and options
+  allMiddleware.push(...(config.middleware ?? []))
+  allMiddleware.push(...(options.middleware ?? []))
 
   const { App } = createApp({
     routes: options.routes,

package/src/error-overlay.ts

@@ -0,0 +1,121 @@
+/**
+ * Dev-only error overlay for SSR/loader errors.
+ * Renders a styled HTML page with the error stack trace.
+ */
+export function renderErrorOverlay(error: Error): string {
+  const title = escapeHtml(error.message || 'Unknown error')
+  const stack = escapeHtml(error.stack || '')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>SSR Error — Pyreon Zero</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+      background: #1a1a2e;
+      color: #e0e0e0;
+      min-height: 100vh;
+      padding: 2rem;
+    }
+    .overlay {
+      max-width: 900px;
+      margin: 0 auto;
+    }
+    .header {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      margin-bottom: 1.5rem;
+    }
+    .badge {
+      background: #e74c3c;
+      color: white;
+      padding: 0.25rem 0.75rem;
+      border-radius: 4px;
+      font-size: 0.75rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+    .label {
+      color: #888;
+      font-size: 0.85rem;
+    }
+    .message {
+      font-size: 1.25rem;
+      color: #ff6b6b;
+      margin-bottom: 1.5rem;
+      line-height: 1.5;
+      word-break: break-word;
+    }
+    .stack {
+      background: #16213e;
+      border: 1px solid #2a2a4a;
+      border-radius: 8px;
+      padding: 1.25rem;
+      overflow-x: auto;
+      font-size: 0.8rem;
+      line-height: 1.7;
+      white-space: pre-wrap;
+      word-break: break-all;
+    }
+    .stack .at { color: #888; }
+    .stack .file { color: #4ecdc4; }
+    .hint {
+      margin-top: 1.5rem;
+      padding: 1rem;
+      background: #1e2a45;
+      border-radius: 6px;
+      border-left: 3px solid #3498db;
+      font-size: 0.8rem;
+      color: #aaa;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="overlay">
+    <div class="header">
+      <span class="badge">SSR Error</span>
+      <span class="label">Pyreon Zero — Dev Mode</span>
+    </div>
+    <div class="message">${title}</div>
+    <pre class="stack">${formatStack(stack)}</pre>
+    <div class="hint">
+      This error occurred during server-side rendering. Check the terminal for
+      the full stack trace. This overlay is only shown in development.
+    </div>
+  </div>
+</body>
+</html>`
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function formatStack(stack: string): string {
+  return stack
+    .split('\n')
+    .map((line) => {
+      if (line.includes('at ')) {
+        const fileMatch = line.match(/\(([^)]+)\)/)
+        if (fileMatch) {
+          return line.replace(
+            fileMatch[0],
+            `(<span class="file">${fileMatch[1]}</span>)`,
+          )
+        }
+      }
+      return line
+    })
+    .join('\n')
+}