Skip to main content

Quik Framework :: HTTP Base

Provides an abstract HTTP engine with routing utilities. The module loads locales, optionally initializes a pluggable HTTP engine, and manages start/stop during boot hooks.

Installation​

npm install @quik/http

Configuration​

Common settings (env overrides):

  • HTTP_LISTEN (default: 127.0.0.1)
  • HTTP_PORT (default: 7200)
  • HTTP_URLS_APP (default: http://HTTP_LISTEN:HTTP_PORT)
  • HTTP_URLS_UI (default: http://HTTP_LISTEN:HTTP_PORT)
  • API_BASE_PATH (default: /api/v1)
  • DOCS_BASE_PATH (default: /api/docs)
  • COOKIE_DOMAIN (default: localhost)
  • COOKIE_SECURE (default: false)
  • CORS_ORIGIN, CORS_METHODS
  • SESSION_SECRET
  • HTTP_BODY_JSON_LIMIT (default: 1mb)
  • HTTP_BODY_URLENCODED_LIMIT (default: 1mb)
  • HTTP_BODY_TEXT_LIMIT (default: 1mb)
  • HTTP_REQUEST_TIMEOUT_MS (default: 0, disables request timeout)
  • HTTP_HEADERS_TIMEOUT_MS (default: 0, disables header timeout)
  • HTTP_SHUTDOWN_TIMEOUT_MS (default: 15000)
  • HTTP_STATIC_CONTENT_SERVE, HTTP_STATIC_CONTENT_GLOBAL
  • HTTP_STATIC_CONTENT_FOLDER (default: ./public)
  • HTTP_STATIC_CONTENT_PATH (default: root)
  • HTTP_STATIC_SINGLE_PAGE_APPLICATION_ENABLE
  • HTTP_STATIC_SINGLE_PAGE_APPLICATION_INDEX_FILE (default: index.html)

Default response headers can be configured via http.headers in your configuration file. Endpoint-specific headers override these defaults.

Cookie defaults are configured through http.cookie.domain and http.cookie.secure. HTTP engine implementations use these values when writing or clearing cookies unless endpoint code passes explicit cookie options.

Static SPA fallback is configured under http.static.singlePageApplication. When enabled, engine implementations can rewrite browser navigation requests to the configured HTML entry file.

Usage​

Define routes with decorators:

import { Decorators, QRoute } from '@quik/http';

@Decorators.Route.Route('/health')
export class HealthRoute extends QRoute {
  @Decorators.Endpoint.GET('/')
  async get(event) {
    event.setCookie('lastHealthCheck', 'ok', { sameSite: 'lax' });

    return { status: 'ok' };
  }
}

API Highlights​

  • QHTTPEngine base class for HTTP engines.
  • QContext base class for adapter-specific request/response context wrappers.
  • QEvent endpoint event wrapper for headers, parameters, body data, files, services, translations, and cookies.
  • Decorators.Route and Decorators.Endpoint for route definitions.
  • QRouter stores registered routes.
  • Responses helpers for standardized responses.
  • IQCookieOptions describes cookie write and clear options shared by HTTP adapters.
  • TooManyRequestsError — maps to HTTP 429; i18n in all 8 supported languages.
  • @RateLimit({ max, windowMs }) — endpoint decorator that enforces a fixed-window rate limit keyed on client IP.
  • IQRateLimiter / QInMemoryRateLimiter — interface and default implementation. Call setRateLimiter(impl) to swap in a Redis or other backend.

Endpoint events and cookies​

Endpoint handlers receive a QEvent. The event exposes validated body, query, and path entities, request metadata, custom request objects, translation helpers, scoped service resolution, and cookie helpers.

import { Decorators, QRoute, type IQEvent } from '@quik/http';

@Decorators.Route.Route('/session')
export class SessionRoute extends QRoute {
  @Decorators.Endpoint.GET('/')
  async read(event: IQEvent) {
    return {
      requestId: event.requestId,
      sessionId: event.getCookie('sessionId') ?? null
    };
  }

  @Decorators.Endpoint.POST('/')
  async write(event: IQEvent) {
    event.setCookie('sessionId', 'abc123', {
      httpOnly: true,
      sameSite: 'lax',
      secure: true
    });

    return { status: 'created' };
  }

  @Decorators.Endpoint.DELETE('/')
  async clear(event: IQEvent) {
    event.clearCookie('sessionId');

    return { status: 'cleared' };
  }
}

Rate limiting​

import { Decorators, QRoute } from '@quik/http';
import { RateLimit } from '@quik/http';

@Decorators.Route.Route('/search')
export class SearchRoute extends QRoute {
  @RateLimit({ max: 10, windowMs: 60_000 }) // 10 req/min per IP
  @Decorators.Endpoint.GET('/')
  async search() {
    return { results: [] };
  }
}

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the http API section.