http.server: add declarations

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarantoolscript",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "author": "Vitaliy Artemov [email protected]",
   "description": "TypeScript definitions for Tarantool Lua API.",
   "repository": {

src/http.server.d.ts

@@ -0,0 +1 @@
+export * from './rocks/http.server/HttpServer';

src/rocks/http.server/HttpRequest.d.ts

@@ -0,0 +1,118 @@
+import { HttpMethod } from '../../builtin/http.client/HttpMethod';
+import { HttpResponse } from './HttpResponse';
+
+export interface HttpRequest {
+  /**
+   * HTTP request type (GET, POST etc).
+   */
+  method: HttpMethod;
+
+  /**
+   * Request path.
+   */
+  path: string;
+
+  /**
+   * Request path without decoding.
+   */
+  path_raw: string;
+
+  /**
+   * Request arguments.
+   */
+  query: LuaTable<string, unknown>;
+
+  /**
+   * HTTP version (for example, { 1, 1 } is HTTP/1.1).
+   */
+  proto: [number, number];
+
+  /**
+   * Normalized request headers. A normalized header is in the lower case, all headers joined together into a single string.
+   */
+  headers: LuaTable<string, stirng>;
+
+  /**
+   * A Lua table with information about the remote peer (`like socket:peer()`).
+   */
+  peer: { host: string, family: string, type: string, protocol: string, port: number };
+
+  /**
+   * Returns a first line of the http request (for example, `PUT /path HTTP/1.1`).
+   */
+  request_line(): string;
+
+  /**
+   * Reads the raw request body as a stream (see `socket:read()`).
+   */
+  read({ delimiter: string, chunk: number }, timeout: number): void;
+
+  /**
+   * @returns A Lua table from a JSON request.
+   */
+  json(): LuaTable<string, unknown> | unknown[];
+
+  /**
+   * @param name Parameter name.
+   * @returns A single POST request a parameter value.
+   */
+  post_param(name: string): unknown;
+
+  /**
+   * @returns All parameters as a Lua table.
+   */
+  post_param(): LuaTable<string, unknown>;
+
+  /**
+   * @param name Parameter name.
+   * @returns a single GET request parameter value.
+   */
+  query_param(name: string): unknown;
+
+  /**
+   * @returns a Lua table with all arguments.
+   */
+  query_param(): LuaTable<string, unknown>;
+
+  /**
+   * @returns any request parameter, either GET or POST.
+   */
+  param(name: string): unknown;
+
+  /**
+   * To get a cookie in the request. if `raw` option was set then cookie will not be unescaped, otherwise cookie's value will be unescaped.
+   */
+  cookie(name: string, options?: { raw?: boolean }): string;
+
+  /**
+   * Get a variable "stashed" when dispatching a route.
+   */
+  stash(name: string): unknown;
+
+  /**
+   * Set a variable "stashed" when dispatching a route.
+   *
+   * Special stash names:
+   * - `controller` - the controller name.
+   * - `action` - the handler name in the controller.
+   * - `format` - the current output format (e.g. `html`, `txt`).
+   * Is detected automatically based on the request's `path` (for example, `/abc.js` sets `format` to `js`).
+   * When producing a response, `format` is used to serve the response's 'Content-type:'.
+   */
+  stash(name: string, value: unknown): void;
+
+  /**
+   * @returns the route's exact URL.
+   */
+  url_for(name: string, args: unknown, query: unknown): string;
+
+  /**
+   * Create a Response object with a rendered template.
+   */
+  render(renderObject: AnyTable): HttpResponse;
+
+  /**
+   * Create a Response object with an HTTP redirect.
+   */
+  redirect_to(url: string): ResponseObject;
+}

src/rocks/http.server/HttpResponse.d.ts

@@ -0,0 +1,23 @@
+export interface HttpResponse {
+  /**
+   * HTTP response code.
+   */
+  status?: number;
+
+  /**
+   * A Lua table with normalized headers.
+   */
+  headers?: LuaTable<string, string>;
+
+  /**
+   * Response body (string | table | wrapped_iterator).
+   */
+  body?: unknown;
+
+  /**
+   * Adds Set-Cookie headers to `resp.headers`
+   * If raw option was set then cookie will not be escaped, otherwise cookie's value and path will be escaped
+   * @param param1
+   */
+  setcookie?(cookie: { name: string, value: string, path: string, expires: string, domain: string}, options?: { raw?: boolean }): void;
+}

src/rocks/http.server/HttpRouteOptions.d.ts

@@ -0,0 +1,50 @@
+import { HttpMethod } from './../../builtin/http.client/HttpMethod';
+
+export interface HttpRouteOptions {
+  /**
+   * A template file name (can be relative to. `{app_dir}/templates`, where `app_dir` is the path set when creating the server).
+   * If no template file name extension is provided, the extension is set to "`.html.el`", meaning HTML with embedded Lua.
+   */
+  file?: string;
+
+  /**
+   * Template Lua variable name, in case the template is a Lua variable.
+   * If `template` is a function, it's called on every request to get template body. This is useful if template body must be taken from a database.
+   */
+  template?: string | (() => string);
+
+  /**
+   * Route path, as described earlier.
+   *
+   * @example
+   * ```
+   * '/'                 -- a simple route
+   * '/abc'              -- a simple route
+   * '/abc/:cde'         -- a route using a simple regular expression
+   * '/abc/:cde/:def'    -- a route using a simple regular expression
+   * '/ghi*path'         -- a route using an extended regular expression
+   * ```
+   */
+  path: string;
+
+  /**
+   * Route name.
+   */
+  name?: string;
+
+  /**
+   * Method on the route like `POST`, `GET`, `PUT`, `DELETE`
+   * @default GET
+   */
+  method?: HttpMethod;
+
+  /**
+   * Option that overrides the server parameter of the same name but only for current route.
+   */
+  log_requests?: boolean | ((fmt: string, ...args: any[]) => unknown);
+
+  /**
+   * Option that overrides the server parameter of the same name but only for current route.
+   */
+  log_errors?: boolean | ((fmt: string, ...args: any[]) => unknown);
+}

src/rocks/http.server/HttpServer.d.ts

@@ -0,0 +1,12 @@
+/** @noSelfInFile */
+
+import { HttpServerOptions } from './HttpServerOptions';
+import { HttpServerObject } from './HttpServerObject';
+
+/**
+ * host and port must contain:
+ * - For tcp socket: the host and port to bind to.
+ * - For unix socket: `unix/` and path to socket (for example `/tmp/http-server.sock`) to bind to.
+ * @customName new
+ */
+export declare function new_(host: string, port: number | string, options?: HttpServerOptions): HttpServerObject;

src/rocks/http.server/HttpServerObject.ts

@@ -0,0 +1,47 @@
+import { HttpRequest } from './HttpRequest';
+import { HttpResponse } from './HttpResponse';
+import { HttpRouteOptions } from './HttpRouteOptions';
+
+export interface HttpServerObject {
+  start(): void;
+
+  stop(): void;
+
+  /**
+   * Automatically route requests between different handlers, depending on the request path.
+   * The routing API is inspired by [Mojolicious](https://docs.mojolicious.org/Mojolicious/Guides/Routing) API.
+   * @param options Lua table.
+   * @param handler The route handler to be used to produce a response to the request.
+   *
+   * The typical usage is to avoid passing file and template arguments, since they take time to evaluate,
+   * but these arguments are useful for writing tests or defining HTTP servers with just one "route".
+   *
+   * The handler can also be passed as a string of the form `filename#functionname`.
+   * In that case, the handler body is taken from a file in the `{app_dir}/controllers directory`.
+   */
+  route(options: HttpRouteOptions, handler: string | ((request: HttpRequest) => HttpResponse)): void;
+
+  /**
+   * Helpers are special functions that are available in all HTML templates. These functions must be defined when creating an `httpd` object.
+   *
+   * If `handler` is `undefined`, helper will be deleted.
+   */
+  helper(name: string, handler: ((controller: unknown, ...args: unknown[]) => unknown) | undefined): void;
+
+  /**
+   * Is invoked before a request is routed to a handler. The first argument of the hook is the HTTP request to be handled.
+   * The return value of the hook is ignored.
+   *
+   * This hook could be used to log a request, or modify request headers.
+   */
+  before_dispatch?: (httpd: HttpServerObject, request: HttpRequest) => unknown;
+
+  /**
+   * Is invoked after a handler for a route is executed.
+   *
+   * The arguments of the hook are the request passed into the handler, and the response produced by the handler.
+   *
+   * This hook can be used to modify the response. The return value of the hook is ignored.
+   */
+  after_dispatch?: (request: HttpRequest, response: HttpResponse) => unknown;
+}

src/rocks/http.server/HttpServerOptions.d.ts

@@ -0,0 +1,67 @@
+import { HttpRequest } from './HttpRequest';
+import { HttpResponse } from './HttpResponse';
+import { HttpServerObject } from './HttpServerObject';
+
+export interface HttpServerOptions {
+  /**
+   * A limit for HTTP request header size.
+   * @default 4096 bytes
+   */
+  max_header_size?: number;
+
+  /**
+   * A timeout until the server stops reading HTTP headers sent by the client.
+   * The server closes the client connection if the client doesn't send its headers within the given amount of time.
+   * @default 100 seconds
+   */
+  header_timeout?: number;
+
+  /**
+   * A path to the directory with HTML templates and controllers.
+   * @default .
+   */
+  app_dir?: string;
+
+  /**
+   * A Lua function to handle HTTP requests (this is a handler to use if the module "routing" functionality is not needed).
+   */
+  handler?: (server: HttpServerObject, request: HttpRequest) => HttpResponse;
+
+  /**
+   * The character set for server responses.
+   */
+  charset?: 'text/html' | 'text/plain' | 'application/json';
+
+  /**
+   * Return application errors and backtraces to the client (like PHP). Disabled by default (`since 1.2.0`).
+   */
+  display_errors?: boolean;
+
+  /**
+   * Log incoming requests. This parameter can receive:
+   * - function value, supporting C-style formatting: `log_requests(fmt, ...)`, where `fmt` is a format string and ... is Lua Varargs,
+   * holding arguments to be replaced in `fmt`.
+   * - boolean value, where `true` choose default `log.info` and false disable request logs at all.
+   *
+   * By default uses `log.info` function for requests logging.
+   */
+  log_requests?: boolean | ((fmt: string, ...args: any[]) => unknown);
+
+  /**
+   * Same as the `log_requests` option but is used for error messages logging. By default uses `log.error()` function.
+   */
+  log_errors?: boolean | ((fmt: string, ...args: any[]) => unknown);
+
+  /**
+   * Disables keep-alive connections with misbehaving clients.
+   * Parameter accept a table that contains a user agents names. By default table is empty.
+   */
+  disable_keepalive?: string[];
+
+  /**
+   * Maximum amount of time an idle (keep-alive) connection will remain idle before closing.
+   * When the idle timeout is exceeded, HTTP server closes the keepalive connection.
+   * @default 0 seconds (disabled)
+   */
+  idle_timeout?: number;
+}

src/rocks/http.server/index.d.ts

@@ -0,0 +1,5 @@
+export * from './HttpRequest';
+export * from './HttpResponse';
+export * from './HttpRouteOptions';
+export * from './HttpServerOptions';
+export * from './HttpServerObject';

src/rocks/index.d.ts

@@ -6,12 +6,12 @@
 /** @todo icu-date https://github.com/tarantool/icu-date#readme */
 /** @todo tracing https://github.com/tarantool/tracing/ */
 /** @todo avro-schema https://github.com/tarantool/avro-schema/blob/master/README.md */
-/** @todo http https://github.com/tarantool/http/blob/master/README.md */
 /** @todo icu-date https://github.com/tarantool/http/blob/master/README.md */
 /** @todo kafka https://github.com/tarantool/kafka/blob/master/README.md */
 /** @todo luacheck https://github.com/tarantool/luacheck?tab=readme-ov-file */
 /** @todo luarapidxml https://github.com/tarantool/luarapidxml/blob/master/README.md */
 /** @todo membership https://www.tarantool.io/en/doc/latest/reference/reference_rock/membership/#membership */
 
 
-export * as luatest from './luatest';
+export * from './http.server';
+export * from './luatest';