@alwatr/nanotron-api-server 4.10.1 → 9.1.0

package/src/api-server-response.ts

@@ -0,0 +1,179 @@
+import {createLogger} from '@alwatr/logger';
+
+import {type HttpStatusCode, HttpStatusCodes, HttpStatusMessages} from './const.js';
+
+import type {NanotronClientRequest} from './api-client-request.js';
+import type {HttpResponseHeaders, ErrorResponse, NativeServerResponse} from './type.js';
+
+/**
+ * Configuration options for the Nanotron Api Server Response.
+ */
+export interface NanotronServerResponseConfig {
+  clientRequest: NanotronClientRequest;
+}
+
+export class NanotronServerResponse {
+  public readonly clientRequest: NanotronClientRequest;
+
+  public readonly raw_: NativeServerResponse;
+
+  public readonly headers: HttpResponseHeaders;
+
+  protected readonly logger_;
+
+  protected hasBeenSent_ = false;
+  public get hasBeenSent(): boolean {
+    return this.hasBeenSent_;
+  }
+
+  constructor(nanotronClientRequest: NanotronClientRequest, nativeServerResponse: NativeServerResponse) {
+    // Store public properties.
+    this.clientRequest = nanotronClientRequest;
+    this.raw_ = nativeServerResponse;
+
+    // Create logger.
+    this.logger_ = createLogger(`nt-server-response(${this.clientRequest.remoteAddress})`);
+    this.logger_.logMethodArgs?.('new', this.clientRequest.url.debugId);
+
+    // Set default reply headers.
+    this.headers = {
+      server: 'Alwatr Nanotron',
+      'content-type': 'text/plain charset=UTF-8',
+    };
+
+    const crossOrigin = this.clientRequest.routeOption?.crossOrigin;
+    if (crossOrigin?.enable === true) {
+      this.headers['access-control-allow-origin'] = crossOrigin.origin;
+      this.headers['access-control-allow-methods'] = crossOrigin.methods;
+      this.headers['access-control-allow-headers'] = crossOrigin.headers;
+      this.headers['access-control-max-age'] = crossOrigin.maxAge;
+    }
+  }
+
+  public get statusCode(): HttpStatusCode {
+    return this.raw_.statusCode as HttpStatusCode;
+  }
+
+  public set statusCode(value: HttpStatusCode) {
+    this.raw_.statusCode = value;
+  }
+
+  protected applyHeaders_() {
+    this.logger_.logMethodArgs?.('applyHeaders_', this.headers);
+    for (const key in this.headers) {
+      this.raw_.setHeader(key, this.headers[key as Lowercase<string>]!);
+    }
+  }
+
+  public replyErrorResponse(errorResponse: ErrorResponse): void {
+    this.logger_.logMethod?.('replyErrorResponse');
+    this.clientRequest.terminatedHandlers = true;
+    this.headers['content-type'] = 'application/json';
+    let meta = '';
+    if (errorResponse.meta !== undefined) {
+      const metaType = typeof errorResponse.meta;
+      if (metaType === 'string' || metaType === 'number' || metaType === 'boolean' || errorResponse.meta === null) {
+        meta = `,"meta":"${errorResponse.meta}"`;
+      }
+      else if (metaType === 'object') {
+        meta = `,"meta":${JSON.stringify(errorResponse.meta)}`;
+      }
+    }
+    const responseString = `{"ok":false,"errorCode":"${errorResponse.errorCode}","errorMessage":"${errorResponse.errorMessage}"${meta}}`;
+    this.reply(responseString);
+  }
+
+  public replyError(error?: Error | string | JsonObject | unknown): void {
+    this.logger_.logMethodArgs?.('replyError', {error});
+
+    this.clientRequest.terminatedHandlers = true;
+    let statusCode = this.statusCode;
+
+    if (statusCode < HttpStatusCodes.Error_Client_400_Bad_Request) {
+      this.statusCode = statusCode = 500;
+    }
+
+    if (error instanceof Error) {
+      this.replyErrorResponse({
+        ok: false,
+        errorCode: (error.name === 'Error' ? 'error_' + statusCode : (error.name + '').toLowerCase()) as Lowercase<string>,
+        errorMessage: error.message,
+      });
+    }
+    else if (typeof error === 'string') {
+      this.replyErrorResponse({
+        ok: false,
+        errorCode: ('error_' + statusCode) as Lowercase<string>,
+        errorMessage: error,
+      });
+    }
+    else if (typeof error === 'object' && error !== null) {
+      this.replyJson(error as JsonObject);
+    }
+    else {
+      this.replyErrorResponse({
+        ok: false,
+        errorCode: ('error_' + statusCode) as Lowercase<string>,
+        errorMessage: HttpStatusMessages[statusCode],
+      });
+    }
+  }
+
+  public replyJson(responseJson: JsonObject): void {
+    this.logger_.logMethodArgs?.('replyJson', {responseJson});
+
+    let responseString: string;
+    try {
+      responseString = JSON.stringify(responseJson);
+    }
+    catch (error) {
+      this.logger_.error('replyJson', 'reply_json_stringify_failed', error, this.clientRequest.url.debugId);
+      this.statusCode = HttpStatusCodes.Error_Server_500_Internal_Server_Error;
+      this.replyErrorResponse({
+        ok: false,
+        errorCode: 'reply_json_stringify_failed',
+        errorMessage: 'Failed to stringify response JSON.',
+      });
+      return;
+    }
+
+    this.headers['content-type'] = 'application/json';
+    this.reply(responseString);
+  }
+
+  public reply(context: string | Buffer): void {
+    this.logger_.logMethodArgs?.('reply', this.clientRequest.url.debugId);
+
+    if (this.raw_.writableFinished && this.hasBeenSent_ === false) {
+      // The response has already been sent by direct access to the server api.
+      this.logger_.accident('reply', 'server_response_writable_finished_directly');
+      this.hasBeenSent_ = true;
+    }
+
+    if (this.hasBeenSent_) {
+      this.logger_.accident('reply', 'reply_already_sent', {
+        url: this.clientRequest.url.debugId,
+        replySent: this.hasBeenSent_,
+        writableFinished: this.raw_.writableFinished,
+      });
+      return;
+    }
+
+    this.hasBeenSent_ = true;
+
+    try {
+      if (typeof context === 'string') {
+        context = Buffer.from(context);
+      }
+
+      this.headers['content-length'] = context.byteLength;
+
+      this.applyHeaders_();
+      this.raw_.end(context, 'binary');
+    }
+    catch (error) {
+      this.logger_.error('reply', 'server_response_error', error, this.clientRequest.url.debugId);
+      this.hasBeenSent_ = false;
+    }
+  }
+}

package/src/api-server.ts

@@ -0,0 +1,337 @@
+import {createServer} from 'node:http';
+
+import {createLogger} from '@alwatr/logger';
+
+import {NanotronClientRequest} from './api-client-request.js';
+import {HttpStatusCodes, HttpStatusMessages} from './const.js';
+import {NanotronUrl} from './url.js';
+
+import type {DefineRouteOption, MatchType, NativeClientRequest, NativeServerResponse} from './type.js';
+import type {Duplex} from 'node:stream';
+
+/**
+ * Configuration options for the NanotronApiServer.
+ */
+export interface NanotronApiServerConfig {
+  /**
+   * The port number to listen on.
+   *
+   * @default 80
+   */
+  port?: number;
+
+  /**
+   * The hostname to listen on.
+   *
+   * @default '0.0.0.0'
+   */
+  host?: string;
+
+  /**
+   * Sets the timeout (ms) for receiving the entire request from the client.
+   *
+   * @default 10_000 ms
+   */
+  requestTimeout?: number;
+
+  /**
+   * Sets the timeout (ms) for receiving the complete HTTP headers from the client.
+   *
+   * This should be bigger than `keepAliveTimeout + your server's expected response time`.
+   *
+   * @default 130_000 ms
+   */
+  headersTimeout?: number;
+
+  /**
+   * Sets the timeout (ms) for receiving the complete HTTP headers from the client.
+   *
+   * @default 120_000 ms
+   */
+  keepAliveTimeout?: number;
+
+  /**
+   * Add /health route.
+   *
+   * @default true
+   */
+  healthRoute?: boolean;
+
+  /**
+   * Add OPTIONS route for preflight requests to allow access origins.
+   *
+   * @default {enable: false, origin: '*', methods: '*', headers: '*', maxAge: 86_400}
+   */
+  crossOrigin?: {
+    enable: boolean;
+    origin: string;
+    methods: string;
+    headers: string;
+    maxAge: string | number;
+  };
+
+  /**
+   * A prefix to be added to the beginning of the `url` of all defined routes.
+   *
+   * @default '/api/'
+   */
+  prefix?: `/${string}/` | '/';
+
+  /**
+   * The maximum size of the request body in bytes.
+   *
+   * @default `1_048_576` (1MiB)
+   */
+  bodyLimit?: number;
+}
+
+export class NanotronApiServer {
+  protected static readonly defaultConfig_: Readonly<Required<NanotronApiServerConfig>> = {
+    host: '0.0.0.0',
+    port: 80,
+    requestTimeout: 10_000,
+    headersTimeout: 130_000,
+    keepAliveTimeout: 120_000,
+    healthRoute: true,
+    crossOrigin: {
+      enable: false,
+      origin: '*',
+      methods: '*',
+      headers: '*',
+      maxAge: 86_400, // 24h
+    },
+    prefix: '/api/',
+    bodyLimit: 1_048_576, // 1MiB
+  };
+
+  public readonly config_: Required<NanotronApiServerConfig>;
+  protected readonly logger_;
+
+  public readonly httpServer;
+
+  protected readonly routeHandlerList__: Record<MatchType, DictionaryOpt<DictionaryOpt<Required<DefineRouteOption>>>>;
+
+  constructor(config?: Partial<NanotronApiServerConfig>) {
+    // Merge the config with the default config.
+    this.config_ = {
+      ...NanotronApiServer.defaultConfig_,
+      ...config,
+    };
+
+    // Create logger.
+    this.logger_ = createLogger('nt-api-server' + (this.config_.port !== 80 ? ':' + this.config_.port : ''));
+    this.logger_.logMethodArgs?.('new', {config: this.config_});
+
+    // Bind methods.
+    this.handleClientRequest_ = this.handleClientRequest_.bind(this);
+    this.handleServerError_ = this.handleServerError_.bind(this);
+    this.handleClientError_ = this.handleClientError_.bind(this);
+
+    // Initialize route handler list.
+    this.routeHandlerList__ = {
+      exact: {},
+      startsWith: {},
+    };
+
+    // Create the HTTP server.
+    this.httpServer = createServer(
+      {
+        keepAlive: true,
+        keepAliveInitialDelay: 0,
+        noDelay: true,
+      },
+      this.handleClientRequest_,
+    );
+
+    // Configure the server.
+    this.httpServer.requestTimeout = this.config_.requestTimeout;
+    this.httpServer.keepAliveTimeout = this.config_.keepAliveTimeout;
+    this.httpServer.headersTimeout = this.config_.headersTimeout;
+
+    // Start the server.
+    this.httpServer.listen(this.config_.port, this.config_.host, () => {
+      this.logger_.logOther?.(`listening on ${this.config_.host}:${this.config_.port}`);
+    });
+
+    // Handle server errors.
+    this.httpServer.on('error', this.handleServerError_);
+    this.httpServer.on('clientError', this.handleClientError_);
+
+    this.defineCorsRoute_();
+
+    if (this.config_.healthRoute) {
+      this.defineHealthRoute_();
+    }
+  }
+
+  public close(): void {
+    this.logger_.logMethod?.('close');
+    this.httpServer.close();
+  }
+
+  protected getRouteOption_(url: NanotronUrl): Required<DefineRouteOption> | null {
+    this.logger_.logMethod?.('getRouteOption_');
+
+    if (
+      Object.hasOwn(this.routeHandlerList__.exact, url.method) &&
+      Object.hasOwn(this.routeHandlerList__.exact[url.method]!, url.pathname)
+    ) {
+      return this.routeHandlerList__.exact[url.method]![url.pathname]!;
+    }
+
+    if (Object.hasOwn(this.routeHandlerList__.startsWith, url.method)) {
+      const routeList = this.routeHandlerList__.startsWith[url.method];
+      for (const pathname in routeList) {
+        if (url.pathname.indexOf(pathname) === 0) {
+          return routeList[pathname]!;
+        }
+      }
+    }
+
+    this.logger_.incident?.('getRouteOption_', 'route_not_found', {method: url.method, url: url.pathname});
+    return null;
+  }
+
+  protected setRouteOption_(option: Required<DefineRouteOption>): void {
+    this.logger_.logMethodArgs?.('setRouteOption_', option);
+
+    const routeHandlerList = this.routeHandlerList__[option.matchType];
+
+    routeHandlerList[option.method] ??= {};
+
+    if (Object.hasOwn(routeHandlerList[option.method]!, option.url)) {
+      this.logger_.error('defineRoute', 'route_already_exists', option);
+      throw new Error('route_already_exists');
+    }
+
+    routeHandlerList[option.method]![option.url] = option;
+  }
+
+  public defineRoute<TSharedMeta extends DictionaryOpt = DictionaryOpt>(option: DefineRouteOption<TSharedMeta>): void {
+    const option_: Required<DefineRouteOption<TSharedMeta>> = {
+      matchType: 'exact',
+      preHandlers: [],
+      postHandlers: [],
+      bodyLimit: this.config_.bodyLimit,
+      crossOrigin: this.config_.crossOrigin,
+      ...option,
+    };
+    this.logger_.logMethodArgs?.('defineRoute', option_);
+    this.setRouteOption_(option_ as Required<DefineRouteOption>);
+  }
+
+  protected handleServerError_(error: NodeJS.ErrnoException): void {
+    if (error.code === 'EADDRINUSE') {
+      this.logger_.error('handleServerError_', 'address_in_use', error);
+    }
+    else {
+      this.logger_.error('handleServerError_', 'http_server_error', error);
+    }
+  }
+
+  protected handleClientError_(err: NodeJS.ErrnoException, socket: Duplex): void {
+    this.logger_.accident('handleClientError_', 'http_server_client_error', {
+      errCode: err.code,
+      errMessage: err.message,
+    });
+
+    const errorCode = err.code?.toLowerCase() ?? `error_${HttpStatusCodes.Error_Client_400_Bad_Request}`;
+    const errorMessage = err.message ?? HttpStatusMessages[HttpStatusCodes.Error_Client_400_Bad_Request];
+    const errorResponse = `{"ok":false,"errorCode":"${errorCode}","errorMessage":"${errorMessage}"}`;
+
+    const responseHeaders = [
+      `HTTP/1.1 ${HttpStatusCodes.Error_Client_400_Bad_Request} ${HttpStatusMessages[HttpStatusCodes.Error_Client_400_Bad_Request]}`,
+      'content-type: application/json',
+      `content-length: ${Buffer.byteLength(errorResponse)}`,
+      '\r\n',
+    ].join('\r\n');
+
+    socket.end(responseHeaders + errorResponse);
+  }
+
+  protected async handleClientRequest_(
+    nativeClientRequest: NativeClientRequest,
+    nativeServerResponse: NativeServerResponse,
+  ): Promise<void> {
+    this.logger_.logMethod?.('handleClientRequest_');
+
+    if (nativeClientRequest.url === undefined) {
+      this.logger_.accident('handleClientRequest_', 'http_server_url_undefined');
+      return;
+    }
+
+    const url = new NanotronUrl(nativeClientRequest, this.config_.prefix);
+
+    const routeOption = this.getRouteOption_(url);
+
+    const connection = new NanotronClientRequest(url, nativeClientRequest, nativeServerResponse, routeOption);
+
+    if (routeOption === null) {
+      connection.serverResponse.statusCode = HttpStatusCodes.Error_Client_404_Not_Found;
+      connection.serverResponse.replyError();
+      return;
+    }
+
+    try {
+      for (const handler of routeOption.preHandlers) {
+        await handler.call(connection, connection, connection.serverResponse, connection.sharedMeta);
+        if (connection.terminatedHandlers === true) return; // must check after each pre-handler.
+      }
+
+      await routeOption.handler.call(connection, connection, connection.serverResponse, connection.sharedMeta);
+
+      for (const handler of routeOption.postHandlers) {
+        if (connection.terminatedHandlers === true) return; // must check before each post-handler.
+        await handler.call(connection, connection, connection.serverResponse, connection.sharedMeta);
+      }
+    }
+    catch (error) {
+      this.logger_.error('handleClientRequest_', 'route_handler_error', error, url.debugId);
+
+      if (connection.serverResponse.statusCode < HttpStatusCodes.Error_Client_400_Bad_Request) {
+        connection.serverResponse.statusCode = HttpStatusCodes.Error_Server_500_Internal_Server_Error;
+      }
+      connection.serverResponse.replyError(error);
+    }
+
+    // TODO: handled open remained connections.
+  }
+
+  protected defineHealthRoute_(): void {
+    this.logger_.logMethod?.('defineHealthRoute_');
+
+    this.defineRoute({
+      method: 'GET',
+      url: '/health',
+      handler: function () {
+        const res = this.serverResponse.raw_;
+        res.statusCode = HttpStatusCodes.Success_200_OK;
+        res.setHeader('server', 'Alwatr Nanotron');
+        res.setHeader('content-type', 'application/json');
+        res.end('{"ok":true}');
+      },
+    });
+  }
+
+  protected defineCorsRoute_(): void {
+    this.logger_.logMethod?.('defineCorsRoute_');
+    const crossOrigin = this.config_.crossOrigin;
+    if (crossOrigin?.enable !== true) return;
+    this.defineRoute({
+      method: 'OPTIONS',
+      matchType: 'startsWith',
+      url: '/',
+      handler: function () {
+        const res = this.serverResponse.raw_;
+        res.writeHead(HttpStatusCodes.Success_204_No_Content, {
+          'access-control-allow-origin': crossOrigin.origin,
+          'access-control-allow-methods': crossOrigin.methods,
+          'access-control-allow-headers': crossOrigin.headers,
+          'access-control-max-age': crossOrigin.maxAge + '',
+          'content-length': 0,
+        });
+        res.end();
+      },
+    });
+  }
+}