@strav/http 0.1.0

package/src/http/cookie.ts

@@ -0,0 +1,59 @@
+/** Options for serializing a Set-Cookie header. */
+export interface CookieOptions {
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+  maxAge?: number // seconds
+  path?: string
+  domain?: string
+}
+
+/** Serialize a cookie name/value pair into a Set-Cookie header string. */
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  let cookie = `${name}=${encodeURIComponent(value)}`
+
+  if (options.httpOnly) cookie += '; HttpOnly'
+  if (options.secure) cookie += '; Secure'
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`
+  cookie += `; Path=${options.path ?? '/'}`
+  if (options.domain) cookie += `; Domain=${options.domain}`
+
+  return cookie
+}
+
+/** Parse a Cookie header string into a map of name → value. */
+export function parseCookies(header: string): Map<string, string> {
+  const cookies = new Map<string, string>()
+
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=')
+    if (eq === -1) continue
+    const key = pair.slice(0, eq).trim()
+    const value = decodeURIComponent(pair.slice(eq + 1).trim())
+    cookies.set(key, value)
+  }
+
+  return cookies
+}
+
+/** Return a new Response with a Set-Cookie header appended. */
+export function withCookie(
+  response: Response,
+  name: string,
+  value: string,
+  options?: CookieOptions
+): Response {
+  const headers = new Headers(response.headers)
+  headers.append('Set-Cookie', serializeCookie(name, value, options))
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
+
+/** Return a new Response with a cookie-clearing Set-Cookie header (Max-Age=0). */
+export function clearCookie(response: Response, name: string, options?: CookieOptions): Response {
+  return withCookie(response, name, '', { ...options, maxAge: 0 })
+}

package/src/http/cors.ts

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CorsOptions {
+  /**
+   * Allowed origins. Determines Access-Control-Allow-Origin.
+   *
+   * - `'*'` — allow all origins (incompatible with credentials)
+   * - `string` — a single exact origin
+   * - `string[]` — an allow-list of exact origins
+   * - `RegExp` — pattern tested against the request Origin header
+   * - `(origin: string) => boolean` — callback for custom logic
+   *
+   * @default '*'
+   */
+  origin?: string | string[] | RegExp | ((origin: string) => boolean)
+
+  /**
+   * Allowed HTTP methods for preflight responses.
+   * @default ['GET','HEAD','PUT','PATCH','POST','DELETE']
+   */
+  methods?: string[]
+
+  /**
+   * Allowed request headers for preflight responses.
+   * When unset, mirrors the Access-Control-Request-Headers from the preflight.
+   */
+  allowedHeaders?: string[]
+
+  /** Headers exposed to the browser via Access-Control-Expose-Headers. */
+  exposedHeaders?: string[]
+
+  /**
+   * Include Access-Control-Allow-Credentials: true.
+   * When true, origin cannot be literal `'*'` — the actual request origin is reflected.
+   * @default false
+   */
+  credentials?: boolean
+
+  /**
+   * Preflight cache duration in seconds (Access-Control-Max-Age).
+   * @default 86400
+   */
+  maxAge?: number
+}
+
+/** Resolved config with defaults applied. */
+export interface ResolvedCorsConfig {
+  origin: string | string[] | RegExp | ((origin: string) => boolean)
+  methods: string[]
+  allowedHeaders?: string[]
+  exposedHeaders?: string[]
+  credentials: boolean
+  maxAge: number
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS: ResolvedCorsConfig = {
+  origin: '*',
+  methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
+  credentials: false,
+  maxAge: 86400,
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Merge user options with defaults. */
+export function resolveCorsConfig(options?: CorsOptions): ResolvedCorsConfig {
+  return { ...DEFAULTS, ...options }
+}
+
+/**
+ * Determine the Access-Control-Allow-Origin value for a request origin.
+ * Returns `null` when the origin is not allowed.
+ */
+export function resolveOrigin(
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null
+): string | null {
+  const { origin, credentials } = config
+
+  if (!requestOrigin) return credentials ? null : '*'
+
+  if (origin === '*') return credentials ? requestOrigin : '*'
+  if (typeof origin === 'string') return origin === requestOrigin ? origin : null
+  if (Array.isArray(origin)) return origin.includes(requestOrigin) ? requestOrigin : null
+  if (origin instanceof RegExp) return origin.test(requestOrigin) ? requestOrigin : null
+  if (typeof origin === 'function') return origin(requestOrigin) ? requestOrigin : null
+
+  return null
+}
+
+/** Build a 204 preflight response with CORS headers. */
+export function preflightResponse(
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null,
+  requestHeaders: string | null
+): Response {
+  const allowedOrigin = resolveOrigin(config, requestOrigin)
+
+  if (!allowedOrigin) return new Response(null, { status: 204 })
+
+  const headers = new Headers()
+  headers.set('Access-Control-Allow-Origin', allowedOrigin)
+  headers.set('Access-Control-Allow-Methods', config.methods.join(', '))
+  headers.set('Access-Control-Max-Age', String(config.maxAge))
+
+  if (config.credentials) {
+    headers.set('Access-Control-Allow-Credentials', 'true')
+  }
+
+  if (config.allowedHeaders) {
+    headers.set('Access-Control-Allow-Headers', config.allowedHeaders.join(', '))
+  } else if (requestHeaders) {
+    headers.set('Access-Control-Allow-Headers', requestHeaders)
+  }
+
+  if (allowedOrigin !== '*') {
+    headers.set('Vary', 'Origin')
+  }
+
+  return new Response(null, { status: 204, headers })
+}
+
+/** Return a new Response with CORS headers appended. */
+export function withCorsHeaders(
+  response: Response,
+  config: ResolvedCorsConfig,
+  requestOrigin: string | null
+): Response {
+  const allowedOrigin = resolveOrigin(config, requestOrigin)
+  if (!allowedOrigin) return response
+
+  const headers = new Headers(response.headers)
+  headers.set('Access-Control-Allow-Origin', allowedOrigin)
+
+  if (config.credentials) {
+    headers.set('Access-Control-Allow-Credentials', 'true')
+  }
+
+  if (config.exposedHeaders?.length) {
+    headers.set('Access-Control-Expose-Headers', config.exposedHeaders.join(', '))
+  }
+
+  if (allowedOrigin !== '*') {
+    const existing = headers.get('Vary')
+    if (!existing?.includes('Origin')) {
+      headers.set('Vary', existing ? `${existing}, Origin` : 'Origin')
+    }
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}

package/src/http/index.ts

@@ -0,0 +1,18 @@
+import { app } from '@stravigor/kernel/core/application'
+import Router from './router.ts'
+
+export { default as Context } from './context.ts'
+export { default as Router } from './router.ts'
+export { default as Server } from './server.ts'
+export { compose } from './middleware.ts'
+export { serializeCookie, parseCookies, withCookie, clearCookie } from './cookie.ts'
+export { rateLimit, MemoryStore } from './rate_limit.ts'
+export { Resource } from './resource.ts'
+export type { Handler, Middleware, Next } from './middleware.ts'
+export type { GroupOptions, WebSocketHandlers, WebSocketData } from './router.ts'
+export type { CookieOptions } from './cookie.ts'
+export type { CorsOptions } from './cors.ts'
+export type { RateLimitOptions, RateLimitStore, RateLimitInfo } from './rate_limit.ts'
+
+if (!app.has(Router)) app.singleton(Router)
+export const router = app.resolve(Router)

package/src/http/middleware.ts

@@ -0,0 +1,39 @@
+import type Context from './context.ts'
+
+/** A route handler — receives a Context and returns a Response. */
+export type Handler = (ctx: Context) => Response | Promise<Response>
+
+/** Invokes the next middleware (or the final handler) in the pipeline. */
+export type Next = () => Promise<Response>
+
+/** A middleware function — wraps a handler with before/after logic. */
+export type Middleware = (ctx: Context, next: Next) => Response | Promise<Response>
+
+/**
+ * Compose an array of middleware and a final handler into a single handler.
+ *
+ * Implements the onion model: each middleware wraps the next, and can
+ * inspect or modify the response on the way back.
+ *
+ * @example
+ * const handler = compose([logger, auth], finalHandler)
+ * const response = await handler(ctx)
+ */
+export function compose(middleware: Middleware[], handler: Handler): Handler {
+  return (ctx: Context) => {
+    let index = -1
+
+    function dispatch(i: number): Promise<Response> {
+      if (i <= index) throw new Error('next() called multiple times')
+      index = i
+
+      if (i === middleware.length) {
+        return Promise.resolve(handler(ctx))
+      }
+
+      return Promise.resolve(middleware[i]!(ctx, () => dispatch(i + 1)))
+    }
+
+    return dispatch(0)
+  }
+}

package/src/http/rate_limit.ts

@@ -0,0 +1,173 @@
+import type { Middleware } from './middleware.ts'
+import type Context from './context.ts'
+
+// ---------------------------------------------------------------------------
+// Store interface
+// ---------------------------------------------------------------------------
+
+export interface RateLimitInfo {
+  /** Total allowed requests in the window. */
+  limit: number
+  /** Remaining requests in the current window. */
+  remaining: number
+  /** Unix timestamp (ms) when the window resets. */
+  resetTime: number
+  /** Whether the current request exceeds the limit. */
+  exceeded: boolean
+}
+
+/**
+ * Pluggable storage backend for rate limit counters.
+ * Implement this interface to use Redis, database, or distributed stores.
+ */
+export interface RateLimitStore {
+  increment(key: string, window: number, max: number): RateLimitInfo | Promise<RateLimitInfo>
+  reset(key: string): void | Promise<void>
+}
+
+// ---------------------------------------------------------------------------
+// In-memory store (fixed window)
+// ---------------------------------------------------------------------------
+
+interface WindowEntry {
+  count: number
+  resetTime: number
+}
+
+/**
+ * In-memory rate limit store using fixed time windows.
+ * Entries are lazily cleaned up on access. Suitable for single-process deployments.
+ */
+export class MemoryStore implements RateLimitStore {
+  private windows = new Map<string, WindowEntry>()
+
+  increment(key: string, window: number, max: number): RateLimitInfo {
+    const now = Date.now()
+    const entry = this.windows.get(key)
+
+    if (entry && now < entry.resetTime) {
+      entry.count++
+      return {
+        limit: max,
+        remaining: Math.max(0, max - entry.count),
+        resetTime: entry.resetTime,
+        exceeded: entry.count > max,
+      }
+    }
+
+    const resetTime = now + window
+    this.windows.set(key, { count: 1, resetTime })
+
+    if (this.windows.size > 10_000) this.cleanup(now)
+
+    return { limit: max, remaining: max - 1, resetTime, exceeded: false }
+  }
+
+  reset(key: string): void {
+    this.windows.delete(key)
+  }
+
+  private cleanup(now: number): void {
+    for (const [key, entry] of this.windows) {
+      if (now >= entry.resetTime) this.windows.delete(key)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface RateLimitOptions {
+  /** Time window in milliseconds. @default 60_000 */
+  window?: number
+
+  /** Maximum requests allowed in the window. @default 60 */
+  max?: number
+
+  /**
+   * Extract the rate limit key from the request context.
+   * Defaults to client IP via X-Forwarded-For / X-Real-IP.
+   */
+  keyExtractor?: (ctx: Context) => string
+
+  /** Return `true` to bypass the rate limit check. */
+  skip?: (ctx: Context) => boolean
+
+  /** Custom storage backend. Defaults to an in-memory fixed-window store. */
+  store?: RateLimitStore
+
+  /** Custom response when rate limit is exceeded. */
+  onLimitReached?: (ctx: Context, info: RateLimitInfo) => Response
+
+  /** Whether to add X-RateLimit-* headers to successful responses. @default true */
+  headers?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Default key extractor
+// ---------------------------------------------------------------------------
+
+function defaultKeyExtractor(ctx: Context): string {
+  const forwarded = ctx.header('x-forwarded-for')
+  if (forwarded) return forwarded.split(',')[0]!.trim()
+
+  const realIp = ctx.header('x-real-ip')
+  if (realIp) return realIp
+
+  return 'unknown'
+}
+
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+
+export function rateLimit(options: RateLimitOptions = {}): Middleware {
+  const {
+    window = 60_000,
+    max = 60,
+    keyExtractor = defaultKeyExtractor,
+    skip,
+    store = new MemoryStore(),
+    onLimitReached,
+    headers: addHeaders = true,
+  } = options
+
+  return async (ctx, next) => {
+    if (skip?.(ctx)) return next()
+
+    const key = keyExtractor(ctx)
+    const info = await store.increment(key, window, max)
+
+    if (info.exceeded) {
+      if (onLimitReached) return onLimitReached(ctx, info)
+
+      const retryAfter = Math.ceil((info.resetTime - Date.now()) / 1000)
+      return new Response(JSON.stringify({ error: 'Too Many Requests' }), {
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'X-RateLimit-Limit': String(info.limit),
+          'X-RateLimit-Remaining': '0',
+          'X-RateLimit-Reset': String(Math.ceil(info.resetTime / 1000)),
+          'Retry-After': String(Math.max(0, retryAfter)),
+        },
+      })
+    }
+
+    const response = await next()
+
+    if (!addHeaders) return response
+
+    const headers = new Headers(response.headers)
+    headers.set('X-RateLimit-Limit', String(info.limit))
+    headers.set('X-RateLimit-Remaining', String(info.remaining))
+    headers.set('X-RateLimit-Reset', String(Math.ceil(info.resetTime / 1000)))
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}

package/src/http/resource.ts

@@ -0,0 +1,102 @@
+import { DateTime } from 'luxon'
+import type { PaginationResult, PaginationMeta } from '@stravigor/database/database/query_builder'
+
+// ---------------------------------------------------------------------------
+// Resource base class
+// ---------------------------------------------------------------------------
+
+/**
+ * Base class for API resources (serializers).
+ *
+ * Subclass and implement `define()` to control the shape of JSON output
+ * for a model. Use the static helpers to transform model instances into
+ * plain objects ready for `ctx.json()`.
+ *
+ * @example
+ * class UserResource extends Resource<User> {
+ *   define(user: User) {
+ *     return {
+ *       id: user.id,
+ *       name: user.name,
+ *       email: user.email,
+ *       createdAt: user.createdAt,
+ *     }
+ *   }
+ * }
+ *
+ * return ctx.json(UserResource.make(user))
+ * return ctx.json(UserResource.collection(users))
+ * return ctx.json(UserResource.paginate(paginatedResult))
+ */
+export abstract class Resource<T> {
+  /**
+   * Define the serialized shape for a single model instance.
+   * Return a plain object with the desired keys and values.
+   * DateTime values are automatically converted to ISO 8601 strings.
+   */
+  abstract define(model: T): Record<string, unknown>
+
+  /**
+   * Transform a single model instance into a plain serializable object.
+   * Returns `null` if the input is `null` or `undefined`.
+   */
+  static make<T>(
+    this: new () => Resource<T>,
+    model: T | null | undefined
+  ): Record<string, unknown> | null {
+    if (model === null || model === undefined) return null
+    const instance = new this()
+    return serialize(instance.define(model))
+  }
+
+  /**
+   * Transform an array of model instances into an array of plain objects.
+   */
+  static collection<T>(this: new () => Resource<T>, models: T[]): Record<string, unknown>[] {
+    const instance = new this()
+    return models.map(model => serialize(instance.define(model)))
+  }
+
+  /**
+   * Transform a PaginationResult into a serialized pagination envelope.
+   * Preserves the `meta` object and serializes each item in `data`.
+   */
+  static paginate<T>(
+    this: new () => Resource<T>,
+    result: PaginationResult<T>
+  ): { data: Record<string, unknown>[]; meta: PaginationMeta } {
+    const instance = new this()
+    return {
+      data: result.data.map(model => serialize(instance.define(model))),
+      meta: result.meta,
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively serialize a plain object, converting DateTime → ISO string. */
+function serialize(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = serializeValue(value)
+  }
+  return result
+}
+
+function serializeValue(value: unknown): unknown {
+  if (value === null || value === undefined) return value
+  if (value instanceof DateTime) return value.toISO()
+  if (typeof value === 'bigint') {
+    return value <= Number.MAX_SAFE_INTEGER && value >= Number.MIN_SAFE_INTEGER
+      ? Number(value)
+      : String(value)
+  }
+  if (Array.isArray(value)) return value.map(serializeValue)
+  if (typeof value === 'object' && value !== null && value.constructor === Object) {
+    return serialize(value as Record<string, unknown>)
+  }
+  return value
+}