@mantiq/core 0.0.1

package/src/http/Kernel.ts

@@ -0,0 +1,252 @@
+import type { Container, Constructor } from '../contracts/Container.ts'
+import type { ExceptionHandler } from '../contracts/ExceptionHandler.ts'
+import type { Middleware } from '../contracts/Middleware.ts'
+import type { Router, RouteMatch } from '../contracts/Router.ts'
+import { MantiqRequest } from './Request.ts'
+import { MantiqResponse } from './Response.ts'
+import { Pipeline } from '../middleware/Pipeline.ts'
+import { WebSocketKernel } from '../websocket/WebSocketKernel.ts'
+import { ConfigRepository } from '../config/ConfigRepository.ts'
+
+export class HttpKernel {
+  /**
+   * Global middleware applied to every request, in order.
+   * Override in a subclass (or set via kernel.setGlobalMiddleware) to customise.
+   */
+  protected globalMiddleware: string[] = []
+
+  /**
+   * Named middleware groups (e.g., 'web', 'api').
+   * Route groups can reference these by name.
+   */
+  protected middlewareGroups: Record<string, string[]> = {
+    web: [],
+    api: [],
+  }
+
+  /**
+   * Resolved middleware alias → class map.
+   * Populated by the middleware registration helper below.
+   */
+  private middlewareAliases: Record<string, Constructor<Middleware>> = {}
+
+  constructor(
+    private readonly container: Container,
+    private readonly router: Router,
+    private readonly exceptionHandler: ExceptionHandler,
+    private readonly wsKernel: WebSocketKernel,
+  ) {}
+
+  // ── Middleware registration ───────────────────────────────────────────────
+
+  /**
+   * Register a middleware alias so routes can reference it by name.
+   * @example kernel.registerMiddleware('auth', AuthenticateMiddleware)
+   */
+  registerMiddleware(alias: string, middleware: Constructor<Middleware>): void {
+    this.middlewareAliases[alias] = middleware
+  }
+
+  registerMiddlewareGroup(name: string, middleware: string[]): void {
+    this.middlewareGroups[name] = middleware
+  }
+
+  setGlobalMiddleware(middleware: string[]): void {
+    this.globalMiddleware = middleware
+  }
+
+  /**
+   * Middleware registered by packages that run before the app's global middleware.
+   * Separate from globalMiddleware so setGlobalMiddleware() doesn't overwrite them.
+   */
+  private prependMiddleware: string[] = []
+  private appendMiddleware: string[] = []
+
+  /**
+   * Prepend middleware aliases that run before the app's global middleware.
+   * Useful for packages that need to inject middleware without touching the app's config.
+   */
+  prependGlobalMiddleware(...aliases: string[]): void {
+    for (const alias of aliases) {
+      if (!this.prependMiddleware.includes(alias)) {
+        this.prependMiddleware.push(alias)
+      }
+    }
+  }
+
+  /**
+   * Append middleware aliases that run after the app's global middleware.
+   */
+  appendGlobalMiddleware(...aliases: string[]): void {
+    for (const alias of aliases) {
+      if (!this.appendMiddleware.includes(alias)) {
+        this.appendMiddleware.push(alias)
+      }
+    }
+  }
+
+  // ── Request handling ─────────────────────────────────────────────────────
+
+  /**
+   * Main entry point. Passed to Bun.serve() as the fetch handler.
+   */
+  async handle(bunRequest: Request, server: Server): Promise<Response> {
+    // WebSocket upgrade
+    if (bunRequest.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+      return this.wsKernel.handleUpgrade(bunRequest, server)
+    }
+
+    const request = MantiqRequest.fromBun(bunRequest)
+
+    try {
+      // Combine prepend + global + append middleware
+      const allMiddleware = [...this.prependMiddleware, ...this.globalMiddleware, ...this.appendMiddleware]
+      const globalClasses = this.resolveMiddlewareList(allMiddleware)
+
+      const response = await new Pipeline(this.container)
+        .send(request)
+        .through(globalClasses)
+        .then(async (req) => {
+          // Match route
+          const match = this.router.resolve(req)
+
+          // Merge route params onto request
+          req.setRouteParams(match.params)
+
+          // Resolve route-level middleware
+          const routeClasses = this.resolveMiddlewareList(match.middleware)
+
+          return new Pipeline(this.container)
+            .send(req)
+            .through(routeClasses)
+            .then((req) => this.callAction(match, req))
+        })
+
+      return this.prepareResponse(response)
+    } catch (err) {
+      return this.exceptionHandler.render(request, err)
+    }
+  }
+
+  /**
+   * Start the Bun HTTP server.
+   */
+  async start(): Promise<void> {
+    const config = this.container.make(ConfigRepository)
+    const port = config.get<number>('app.port', 3000)
+    const hostname = config.get<string>('app.host', '0.0.0.0')
+
+    Bun.serve({
+      port,
+      hostname,
+      fetch: (req, server) => this.handle(req, server),
+      websocket: this.wsKernel.getBunHandlers(),
+    })
+
+    console.log(`Server running at http://${hostname === '0.0.0.0' ? 'localhost' : hostname}:${port}`)
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  /**
+   * Call the route action (controller method or closure).
+   * Converts the return value to a Response.
+   */
+  private async callAction(match: RouteMatch, request: MantiqRequest): Promise<Response> {
+    const action = match.action
+
+    let result: any
+
+    if (typeof action === 'function') {
+      result = await action(request)
+    } else if (Array.isArray(action)) {
+      const [ControllerClass, method] = action
+      const controller = this.container.make(ControllerClass)
+      result = await (controller as any)[method](request)
+    } else {
+      throw new Error(`Unresolved string action '${action}'. Controllers must be registered with router.controllers().`)
+    }
+
+    return this.prepareResponse(result)
+  }
+
+  /**
+   * Convert a controller return value to a native Response.
+   */
+  private prepareResponse(value: any): Response {
+    if (value instanceof Response) return value
+    if (value === null || value === undefined) return MantiqResponse.noContent()
+    if (typeof value === 'string') return MantiqResponse.html(value)
+    if (typeof value === 'object' || Array.isArray(value)) return MantiqResponse.json(value)
+    return MantiqResponse.html(String(value))
+  }
+
+  /**
+   * Resolve a list of middleware strings (aliases + parameters) to class constructors.
+   * Expands middleware groups automatically.
+   */
+  private resolveMiddlewareList(list: string[]): Constructor<Middleware>[] {
+    const resolved: Constructor<Middleware>[] = []
+
+    for (const entry of list) {
+      // Check if it's a group name
+      if (this.middlewareGroups[entry]) {
+        resolved.push(...this.resolveMiddlewareList(this.middlewareGroups[entry]!))
+        continue
+      }
+
+      // Parse alias:param1,param2
+      const colonIdx = entry.indexOf(':')
+      const alias = colonIdx === -1 ? entry : entry.slice(0, colonIdx)
+      const params = colonIdx === -1 ? [] : entry.slice(colonIdx + 1).split(',')
+
+      const MiddlewareClass = this.middlewareAliases[alias]
+      if (!MiddlewareClass) {
+        // Try resolving from container by string alias
+        try {
+          const mw = this.container.make<Constructor<Middleware>>(alias)
+          if (params.length > 0) {
+            resolved.push(this.wrapWithParams(mw, params))
+          } else {
+            resolved.push(mw)
+          }
+        } catch {
+          console.warn(`[Mantiq] Unknown middleware alias: '${alias}'`)
+        }
+        continue
+      }
+
+      if (params.length > 0) {
+        resolved.push(this.wrapWithParams(MiddlewareClass, params))
+      } else {
+        resolved.push(MiddlewareClass)
+      }
+    }
+
+    return resolved
+  }
+
+  /**
+   * Wrap a middleware class so setParameters() is called before handle().
+   */
+  private wrapWithParams(
+    MiddlewareClass: Constructor<Middleware>,
+    params: string[],
+  ): Constructor<Middleware> {
+    const container = this.container
+    // @internal: Create a proxy class that injects parameters after instantiation
+    return class ParameterisedMiddleware {
+      private inner: Middleware
+      constructor() {
+        this.inner = container.make(MiddlewareClass)
+        this.inner.setParameters?.(params)
+      }
+      handle(request: MantiqRequest, next: () => Promise<Response>) {
+        return this.inner.handle(request, next)
+      }
+      terminate(request: MantiqRequest, response: Response) {
+        return this.inner.terminate?.(request, response)
+      }
+    } as unknown as Constructor<Middleware>
+  }
+}

package/src/http/Request.ts

@@ -0,0 +1,249 @@
+import type { MantiqRequest as MantiqRequestContract } from '../contracts/Request.ts'
+import type { SessionStore } from '../session/Store.ts'
+import { UploadedFile } from './UploadedFile.ts'
+import { parseCookies } from './Cookie.ts'
+
+export class MantiqRequest implements MantiqRequestContract {
+  private parsedBody: Record<string, any> | null = null
+  private parsedFiles: Record<string, UploadedFile | UploadedFile[]> = {}
+  private parsedQuery: Record<string, string> | null = null
+  private routeParams: Record<string, any> = {}
+  private authenticatedUser: any = null
+  private cookies: Record<string, string> | null = null
+  private sessionStore: SessionStore | null = null
+
+  constructor(
+    private readonly bunRequest: Request,
+    private readonly bunUrl: URL,
+  ) {}
+
+  /**
+   * Create from a Bun Request. Parses the URL once and caches it.
+   */
+  static fromBun(request: Request): MantiqRequest {
+    const url = new URL(request.url)
+    return new MantiqRequest(request, url)
+  }
+
+  // ── HTTP basics ──────────────────────────────────────────────────────────
+
+  method(): string {
+    return this.bunRequest.method.toUpperCase()
+  }
+
+  path(): string {
+    return this.bunUrl.pathname
+  }
+
+  url(): string {
+    return this.bunUrl.pathname + this.bunUrl.search
+  }
+
+  fullUrl(): string {
+    return this.bunRequest.url
+  }
+
+  // ── Input ────────────────────────────────────────────────────────────────
+
+  query(): Record<string, string>
+  query(key: string, defaultValue?: string): string
+  query(key?: string, defaultValue?: string): string | Record<string, string> {
+    if (!this.parsedQuery) {
+      this.parsedQuery = Object.fromEntries(this.bunUrl.searchParams.entries())
+    }
+    if (key === undefined) return this.parsedQuery
+    return this.parsedQuery[key] ?? defaultValue ?? (undefined as any)
+  }
+
+  async input(): Promise<Record<string, any>>
+  async input(key: string, defaultValue?: any): Promise<any>
+  async input(key?: string, defaultValue?: any): Promise<any> {
+    if (!this.parsedBody) {
+      await this.parseBody()
+    }
+    const merged = { ...this.query(), ...this.parsedBody }
+    if (key === undefined) return merged
+    return merged[key] ?? defaultValue
+  }
+
+  async only(...keys: string[]): Promise<Record<string, any>> {
+    const all = await this.input()
+    return Object.fromEntries(keys.filter((k) => k in all).map((k) => [k, all[k]]))
+  }
+
+  async except(...keys: string[]): Promise<Record<string, any>> {
+    const all = await this.input()
+    return Object.fromEntries(Object.entries(all).filter(([k]) => !keys.includes(k)))
+  }
+
+  has(...keys: string[]): boolean {
+    const q = this.query()
+    return keys.every((k) => k in q || (this.parsedBody !== null && k in this.parsedBody))
+  }
+
+  async filled(...keys: string[]): Promise<boolean> {
+    const all = await this.input()
+    return keys.every((k) => all[k] !== undefined && all[k] !== '' && all[k] !== null)
+  }
+
+  // ── Headers & metadata ───────────────────────────────────────────────────
+
+  header(key: string, defaultValue?: string): string | undefined {
+    return this.bunRequest.headers.get(key.toLowerCase()) ?? defaultValue
+  }
+
+  headers(): Record<string, string> {
+    const result: Record<string, string> = {}
+    this.bunRequest.headers.forEach((value, key) => {
+      result[key] = value
+    })
+    return result
+  }
+
+  cookie(key: string, defaultValue?: string): string | undefined {
+    if (!this.cookies) {
+      this.cookies = parseCookies(this.bunRequest.headers.get('cookie'))
+    }
+    return this.cookies[key] ?? defaultValue
+  }
+
+  setCookies(cookies: Record<string, string>): void {
+    this.cookies = cookies
+  }
+
+  ip(): string {
+    // @internal: Bun doesn't expose IP on Request — callers should pass it via middleware if needed
+    return this.header('x-forwarded-for')?.split(',')[0]?.trim()
+      ?? this.header('x-real-ip')
+      ?? '127.0.0.1'
+  }
+
+  userAgent(): string {
+    return this.header('user-agent') ?? ''
+  }
+
+  accepts(...types: string[]): string | false {
+    const acceptHeader = this.header('accept') ?? '*/*'
+    for (const type of types) {
+      if (acceptHeader.includes(type) || acceptHeader.includes('*/*')) {
+        return type
+      }
+    }
+    return false
+  }
+
+  expectsJson(): boolean {
+    const accept = this.header('accept') ?? ''
+    return accept.includes('application/json') || accept.includes('text/json')
+  }
+
+  isJson(): boolean {
+    const ct = this.header('content-type') ?? ''
+    return ct.includes('application/json')
+  }
+
+  // ── Files ────────────────────────────────────────────────────────────────
+
+  file(key: string): UploadedFile | null {
+    const f = this.parsedFiles[key]
+    if (!f) return null
+    return Array.isArray(f) ? (f[0] ?? null) : f
+  }
+
+  files(key: string): UploadedFile[] {
+    const f = this.parsedFiles[key]
+    if (!f) return []
+    return Array.isArray(f) ? f : [f]
+  }
+
+  hasFile(key: string): boolean {
+    return key in this.parsedFiles
+  }
+
+  // ── Route params ─────────────────────────────────────────────────────────
+
+  param(key: string, defaultValue?: any): any {
+    return this.routeParams[key] ?? defaultValue
+  }
+
+  params(): Record<string, any> {
+    return { ...this.routeParams }
+  }
+
+  setRouteParams(params: Record<string, any>): void {
+    this.routeParams = params
+  }
+
+  // ── Session ──────────────────────────────────────────────────────────────
+
+  session(): SessionStore {
+    if (!this.sessionStore) {
+      throw new Error('Session has not been started. Ensure the StartSession middleware is active.')
+    }
+    return this.sessionStore
+  }
+
+  setSession(session: SessionStore): void {
+    this.sessionStore = session
+  }
+
+  hasSession(): boolean {
+    return this.sessionStore !== null
+  }
+
+  // ── Auth ─────────────────────────────────────────────────────────────────
+
+  user<T = any>(): T | null {
+    return this.authenticatedUser as T | null
+  }
+
+  isAuthenticated(): boolean {
+    return this.authenticatedUser !== null
+  }
+
+  setUser(user: any): void {
+    this.authenticatedUser = user
+  }
+
+  // ── Raw ──────────────────────────────────────────────────────────────────
+
+  raw(): Request {
+    return this.bunRequest
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private async parseBody(): Promise<void> {
+    this.parsedBody = {}
+
+    const contentType = this.header('content-type') ?? ''
+
+    try {
+      if (contentType.includes('application/json')) {
+        this.parsedBody = await this.bunRequest.clone().json()
+      } else if (contentType.includes('application/x-www-form-urlencoded')) {
+        const text = await this.bunRequest.clone().text()
+        this.parsedBody = Object.fromEntries(new URLSearchParams(text).entries())
+      } else if (contentType.includes('multipart/form-data')) {
+        const formData = await this.bunRequest.clone().formData()
+        for (const [key, value] of formData.entries()) {
+          if (value instanceof File) {
+            const uploaded = new UploadedFile(value)
+            if (this.parsedFiles[key]) {
+              const existing = this.parsedFiles[key]!
+              this.parsedFiles[key] = Array.isArray(existing)
+                ? [...existing, uploaded]
+                : [existing, uploaded]
+            } else {
+              this.parsedFiles[key] = uploaded
+            }
+          } else {
+            this.parsedBody![key] = value
+          }
+        }
+      }
+    } catch {
+      // Body parsing failed — leave parsedBody as empty object
+    }
+  }
+}

package/src/http/Response.ts

@@ -0,0 +1,112 @@
+import type { CookieOptions, MantiqResponseBuilder } from '../contracts/Response.ts'
+import { serializeCookie } from './Cookie.ts'
+
+/**
+ * Static factory methods for common response types.
+ */
+export class MantiqResponse {
+  static json(data: any, status: number = 200, headers?: Record<string, string>): Response {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { 'Content-Type': 'application/json', ...headers },
+    })
+  }
+
+  static html(content: string, status: number = 200): Response {
+    return new Response(content, {
+      status,
+      headers: { 'Content-Type': 'text/html; charset=utf-8' },
+    })
+  }
+
+  static redirect(url: string, status: number = 302): Response {
+    return new Response(null, {
+      status,
+      headers: { Location: url },
+    })
+  }
+
+  static noContent(): Response {
+    return new Response(null, { status: 204 })
+  }
+
+  static stream(
+    callback: (controller: ReadableStreamDefaultController) => void | Promise<void>,
+  ): Response {
+    const stream = new ReadableStream({ start: callback })
+    return new Response(stream)
+  }
+
+  static download(
+    content: Uint8Array | string,
+    filename: string,
+    mimeType?: string,
+  ): Response {
+    return new Response(content, {
+      headers: {
+        'Content-Type': mimeType ?? 'application/octet-stream',
+        'Content-Disposition': `attachment; filename="${filename}"`,
+      },
+    })
+  }
+}
+
+/**
+ * Chainable response builder for use in middleware and controllers.
+ */
+export class ResponseBuilder implements MantiqResponseBuilder {
+  private statusCode: number = 200
+  private statusExplicitlySet: boolean = false
+  private responseHeaders: Record<string, string> = {}
+  private cookieStrings: string[] = []
+
+  status(code: number): this {
+    this.statusCode = code
+    this.statusExplicitlySet = true
+    return this
+  }
+
+  header(key: string, value: string): this {
+    this.responseHeaders[key] = value
+    return this
+  }
+
+  withHeaders(headers: Record<string, string>): this {
+    Object.assign(this.responseHeaders, headers)
+    return this
+  }
+
+  cookie(name: string, value: string, options?: CookieOptions): this {
+    this.cookieStrings.push(serializeCookie(name, value, options))
+    return this
+  }
+
+  json(data: any): Response {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      ...this.responseHeaders,
+    })
+    for (const c of this.cookieStrings) headers.append('Set-Cookie', c)
+    return new Response(JSON.stringify(data), { status: this.statusCode, headers })
+  }
+
+  html(content: string): Response {
+    const headers = new Headers({
+      'Content-Type': 'text/html; charset=utf-8',
+      ...this.responseHeaders,
+    })
+    for (const c of this.cookieStrings) headers.append('Set-Cookie', c)
+    return new Response(content, { status: this.statusCode, headers })
+  }
+
+  redirect(url: string): Response {
+    const headers = new Headers({ Location: url, ...this.responseHeaders })
+    for (const c of this.cookieStrings) headers.append('Set-Cookie', c)
+    return new Response(null, { status: this.statusExplicitlySet ? this.statusCode : 302, headers })
+  }
+}
+
+/** Shorthand to start a chainable builder */
+export function response(): ResponseBuilder {
+  return new ResponseBuilder()
+}

package/src/http/UploadedFile.ts

@@ -0,0 +1,56 @@
+import { MantiqError } from '../errors/MantiqError.ts'
+
+export class UploadedFile {
+  constructor(private readonly file: File) {}
+
+  /** Original filename */
+  name(): string {
+    return this.file.name
+  }
+
+  /** File extension (without dot) */
+  extension(): string {
+    const parts = this.file.name.split('.')
+    return parts.length > 1 ? (parts[parts.length - 1] ?? '') : ''
+  }
+
+  /** MIME type */
+  mimeType(): string {
+    return this.file.type
+  }
+
+  /** Size in bytes */
+  size(): number {
+    return this.file.size
+  }
+
+  /** File was uploaded without errors */
+  isValid(): boolean {
+    return this.file.size > 0
+  }
+
+  /**
+   * Store the file and return the stored path.
+   * @param path - Directory path to store in
+   * @param options.disk - Storage disk (currently only local filesystem)
+   */
+  async store(path: string, _options?: { disk?: string }): Promise<string> {
+    const filename = `${Date.now()}_${this.file.name}`
+    const fullPath = `${path}/${filename}`
+    const bytes = await this.file.arrayBuffer()
+    await Bun.write(fullPath, bytes)
+    return fullPath
+  }
+
+  async bytes(): Promise<Uint8Array> {
+    return new Uint8Array(await this.file.arrayBuffer())
+  }
+
+  async text(): Promise<string> {
+    return this.file.text()
+  }
+
+  stream(): ReadableStream {
+    return this.file.stream()
+  }
+}