Installation

Thanks to AxiSpark.js, you can easily install the Http Plugin in your project. Follow the steps below to get started.

1. Install the Http Plugin

You can use npm or any other package manager to install the Http Plugin. Run the following command in your project directory:

npm install @axispark/http

2. Import the Http Plugin

Once the installation is complete, you can import the Http Plugin into your project. Add the following line to your code:

import { AxiSparkFactory } from '@axisparkjs/core';
import { HttpPlugin, HttpPluginOptionsFactory } from '@axisparkjs/http';

export const app = AxiSparkFactory.create({
    ...
});

app.use(HttpPlugin, HttpPluginOptionsFactory.create({
    // Configuration options
}));

3. Configure the Http Plugin

Http Plugin offers a HttpPluginOptionsFactory class that allows you to configure the plugin with various options. The HttpPluginOptionsFactory.create() method accepts an object with the following properties:

/**
 * Options for configuring the header-based version resolver.
 */
export interface HeaderVersionOptions {
    type: VersionType.Header;
    header: string;
}

/**
 * Options for configuring the media type-based version resolver.
 */
export interface MediaTypeVersionOptions {
    type: VersionType.MediaType;
    key: string;
}

/**
 * Options for configuring the URI-based version resolver.
 */
export interface UriVersionOptions {
    type: VersionType.Uri;
    defaultVersion?: string;
}

/**
 * Options for configuring the custom version resolver.
 */
export interface CustomVersionOptions {
    type: VersionType.Custom;
    resolver: (req: HttpRequest) => string | undefined;
}

/**
 * A union type for all possible version options.
 */
export type VersionOptions = HeaderVersionOptions | MediaTypeVersionOptions | UriVersionOptions | CustomVersionOptions;

/**
 * Options for configuring the timeout behavior.
 */
export interface TimeoutOptions {
    /**
     * The timeout duration in milliseconds.
     */
    time: number;
    /**
     * The message to display when a timeout occurs. By default, it will display a generic timeout message.
     */
    message?: string | ((time: number) => string);
}

/**
 * Options for configuring HTTP rate limiting.
 */
export interface RateLimitOptions {
    /** The sliding time window in milliseconds. */
    ttl: number;
    /** The maximum number of requests allowed in the window. */
    limit: number;
    /** The response message when a client exceeds the limit. */
    message?: string | ((time: number) => string);
}

/** The reason why a multipart upload was rejected. */
export type FileUploadLimitReason = 'fileSize' | 'files' | 'mimeType';

/**
 * Options for configuring file uploads (`multipart/form-data`).
 */
export interface FileUploadOptions {
    /** Maximum size in bytes allowed per file. */
    maxFileSize: number;
    /** Maximum number of files allowed per request. */
    maxFiles?: number;
    /** Allowed MIME types (e.g. `['image/png', 'application/pdf']`). All allowed if omitted. */
    allowedMimeTypes?: string[];
    /** The message to display when an upload limit is exceeded. */
    message?: string | ((limit: number, reason: FileUploadLimitReason) => string);
}

/**
 * Options for configuring the HTTP plugin.
 */
export interface HttpPluginOptions extends PluginOptions {
    /**
     * The port on which the HTTP server will listen.
     */
    port: number;
    /**
     * The base path for the HTTP server.
     */
    basePath: string;
    /**
     * The HTTP adapter to use. Express or Fastify are supported.
     */
    adapter: HttpAdapterClass;
    /**
     * Whether to use the body parser middleware.
     */
    bodyParser: boolean;
    /**
     * Options for configuring the body parser middleware.
     */
    bodyParserOptions?: any;
    /**
     * Whether to use the URL-encoded middleware.
     */
    urlEncoded?: boolean;
    /**
     * Options for configuring the URL-encoded middleware.
     */
    urlEncodedOptions?: any;
    /**
     * Whether to use CORS middleware.
     */
    cors: boolean;
    /**
     * Options for configuring the CORS middleware.
     */
    corsOptions?: any;
    /**
     * Whether to use the session middleware.
     */
    session: boolean;
    /**
     * Options for configuring the session middleware.
     */
    sessionOptions?: any;
    /**
     * Whether to use the cookie parser middleware.
     */
    cookies: boolean;
    /**
     * Options for configuring the cookie parser middleware.
     */
    cookiesOptions?: any;
    /**
     * Whether to use compression middleware.
     */
    compression: boolean;
    /**
     * Options for configuring the compression middleware.
     */
    compressionOptions?: any;
    /**
     * Whether to use the timeout middleware.
     */
    timeout: boolean;
    /**
     * Options for configuring the timeout middleware.
     */
    timeoutOptions?: TimeoutOptions;
    /** Whether to use HTTP rate limiting. Disabled by default. */
    rateLimit?: boolean;
    /** Default rate limits applied to endpoints without decorator overrides. */
    rateLimitOptions?: RateLimitOptions;
    /** Whether to use the file upload (multipart/form-data) middleware. Disabled by default. */
    fileUpload?: boolean;
    /** Default file upload limits applied to endpoints without decorator overrides. */
    fileUploadOptions?: FileUploadOptions;
    /**
     * Whether to use the versioning guard.
     */
    version: boolean;
    /**
     * Options for configuring the versioning guard.
     */
    versionOptions?: VersionOptions;
    /**
     * Whether to use the health check endpoints.
     */
    healthChecks?: boolean;
    /**
     * Whether to log HTTP requests.
     */
    logHttpRequests?: boolean;
    /**
     * Whether to log HTTP responses.
     */
    logHttpResponses?: boolean;
    /**
     * Whether to log HTTP errors.
     */
    logHttpErrors?: boolean;
    /**
     * Whether to log all errors.
     */
    logErrors?: boolean;
}