@aerokit/sdk 12.44.0

package/dist/dts/http/response.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Provides a static façade (`Response` class) for managing the HTTP response.
+ * This class wraps a native Java HTTP response object, offering methods for setting
+ * status codes, headers, cookies, and writing content (text, JSON, or binary).
+ */
+import { OutputStream } from "@aerokit/sdk/io/streams";
+/**
+ * Defines the structure for an HTTP cookie, including its name, value, and optional attributes.
+ */
+export interface Cookie {
+    /** The name of the cookie. */
+    name: string;
+    /** The value of the cookie. */
+    value: string;
+    /** Key-value map of cookie attributes (e.g., 'maxAge', 'path', 'domain', 'secure', 'httpOnly'). */
+    attributes: {
+        [key: string]: string;
+    };
+}
+/**
+ * The static Response class providing standardized HTTP status codes and methods
+ * for constructing the server's response.
+ */
+export declare class Response {
+    static readonly ACCEPTED = 202;
+    static readonly BAD_GATEWAY = 502;
+    static readonly BAD_REQUEST = 400;
+    static readonly CONFLICT = 409;
+    static readonly CONTINUE = 100;
+    static readonly CREATED = 201;
+    static readonly EXPECTATION_FAILED = 417;
+    static readonly FORBIDDEN = 403;
+    static readonly FOUND = 302;
+    static readonly GATEWAY_TIMEOUT = 504;
+    static readonly GONE = 410;
+    static readonly HTTP_VERSION_NOT_SUPPORTED = 505;
+    static readonly INTERNAL_SERVER_ERROR = 500;
+    static readonly LENGTH_REQUIRED = 411;
+    static readonly METHOD_NOT_ALLOWED = 405;
+    static readonly MOVED_PERMANENTLY = 301;
+    static readonly MOVED_TEMPORARILY = 302;
+    static readonly MULTIPLE_CHOICES = 300;
+    static readonly NO_CONTENT = 204;
+    static readonly NON_AUTHORITATIVE_INFORMATION = 203;
+    static readonly NOT_ACCEPTABLE = 406;
+    static readonly NOT_FOUND = 404;
+    static readonly NOT_IMPLEMENTED = 501;
+    static readonly NOT_MODIFIED = 304;
+    static readonly OK = 200;
+    static readonly PARTIAL_CONTENT = 206;
+    static readonly PAYMENT_REQUIRED = 402;
+    static readonly PRECONDITION_FAILED = 412;
+    static readonly PROXY_AUTHENTICATION_REQUIRED = 407;
+    static readonly REQUEST_ENTITY_TOO_LARGE = 413;
+    static readonly REQUEST_TIMEOUT = 408;
+    static readonly REQUEST_URI_TOO_LONG = 414;
+    static readonly REQUESTED_RANGE_NOT_SATISFIABLE = 416;
+    static readonly RESET_CONTENT = 205;
+    static readonly SEE_OTHER = 303;
+    static readonly SERVICE_UNAVAILABLE = 503;
+    static readonly SWITCHING_PROTOCOLS = 101;
+    static readonly TEMPORARY_REDIRECT = 307;
+    static readonly UNAUTHORIZED = 401;
+    static readonly UNSUPPORTED_MEDIA_TYPE = 415;
+    static readonly USE_PROXY = 305;
+    static readonly UNPROCESSABLE_CONTENT = 422;
+    /**
+     * Mapping between HTTP response codes (string) and their corresponding reason-phrases
+     * as defined in RFC 7231, section 6.1.
+     */
+    static readonly HttpCodesReasons: {
+        "100": string;
+        "101": string;
+        "200": string;
+        "201": string;
+        "202": string;
+        "203": string;
+        "204": string;
+        "205": string;
+        "206": string;
+        "300": string;
+        "301": string;
+        "302": string;
+        "303": string;
+        "304": string;
+        "305": string;
+        "307": string;
+        "400": string;
+        "401": string;
+        "402": string;
+        "403": string;
+        "404": string;
+        "405": string;
+        "406": string;
+        "407": string;
+        "408": string;
+        "409": string;
+        "410": string;
+        "411": string;
+        "412": string;
+        "413": string;
+        "414": string;
+        "415": string;
+        "416": string;
+        "417": string;
+        "422": string;
+        "426": string;
+        "500": string;
+        "501": string;
+        "502": string;
+        "503": string;
+        "504": string;
+        "505": string;
+        /**
+        * Utility method that accepts an HTTP code and returns its corresponding reason-phrase.
+        * @param code The HTTP status code (number).
+        * @returns The reason phrase string.
+        * @throws Error if the code is not a valid integer in the range [100-505].
+        */
+        getReason: (code: number) => string;
+    };
+    /**
+     * Checks if the response façade is currently valid or connected to an active request context.
+     * @returns True if valid, false otherwise.
+     */
+    static isValid(): boolean;
+    /**
+     * Serializes a JavaScript object to JSON, sets the `Content-Type: application/json` header,
+     * and writes the JSON string to the response output stream.
+     * @param obj The JavaScript object to be serialized and sent.
+     */
+    static json(obj: any): void;
+    /**
+     * Writes a string of text to the response body using **UTF-8** encoding.
+     * Note: This method automatically handles flushing the output stream.
+     * @param text The string content to write.
+     */
+    static print(text: string): void;
+    /**
+     * Writes a string of text followed by a newline character (`\n`) to the response body
+     * using **UTF-8** encoding.
+     * @param text The string content to write.
+     */
+    static println(text: string): void;
+    /**
+     * Writes an array of bytes directly to the response output stream, typically used for binary data.
+     * @param bytes The array of bytes to write.
+     */
+    static write(bytes: any[]): void;
+    /**
+     * Checks if the response headers and status have already been sent to the client.
+     * @returns True if the response is committed, false otherwise.
+     */
+    static isCommitted(): boolean;
+    /**
+     * Sets the value of the `Content-Type` header.
+     * @param contentType The MIME type string (e.g., 'text/html', 'application/pdf').
+     */
+    static setContentType(contentType: string): void;
+    /**
+     * Forces any buffered output to be written to the client.
+     */
+    static flush(): void;
+    /**
+     * Closes the response output stream.
+     */
+    static close(): void;
+    /**
+     * Adds a cookie to the response. The cookie object is serialized to JSON before being passed
+     * to the underlying Java facade.
+     * @param cookie The cookie definition object.
+     */
+    static addCookie(cookie: Cookie): void;
+    /**
+     * Checks if a response header with the specified name has already been set.
+     * @param name The name of the header.
+     * @returns True if the header exists, false otherwise.
+     */
+    static containsHeader(name: string): boolean;
+    /**
+     * Encodes a URL for use in redirects or forms, including session information if necessary.
+     * @param url The URL to encode.
+     * @returns The encoded URL string.
+     */
+    static encodeURL(url: string): string;
+    /**
+     * Gets the character encoding used for the response body.
+     * @returns The character encoding string.
+     */
+    static getCharacterEncoding(): string;
+    /**
+     * Encodes a URL for use in the `Location` header of a redirect response.
+     * @param url The redirect URL to encode.
+     * @returns The encoded redirect URL string.
+     */
+    static encodeRedirectURL(url: string): string;
+    /**
+     * Gets the current `Content-Type` header value.
+     * @returns The content type string.
+     */
+    static getContentType(): string;
+    /**
+     * Sends an HTTP error response to the client with the specified status code and optional message.
+     * This bypasses the normal response body writing process.
+     * @param status The HTTP status code (e.g., 404, 500).
+     * @param message An optional message to include in the error response.
+     */
+    static sendError(status: number, message?: string): void;
+    /**
+     * Sets the character encoding to be used for the response body (e.g., 'UTF-8').
+     * @param charset The character set string.
+     */
+    static setCharacterEncoding(charset: string): void;
+    /**
+     * Sends a redirect response (status code 302 by default) to the client.
+     * @param location The new URL to redirect the client to.
+     */
+    static sendRedirect(location: string): void;
+    /**
+     * Sets the `Content-Length` header for the response.
+     * @param length The size of the response body in bytes.
+     */
+    static setContentLength(length: number): void;
+    /**
+     * Sets a response header with the given name and value. If the header already exists, its value is overwritten.
+     * @param name The name of the header.
+     * @param value The value of the header.
+     */
+    static setHeader(name: string, value: string): void;
+    /**
+     * Adds a response header with the given name and value. If the header already exists, a second header with the same name is added.
+     * @param name The name of the header.
+     * @param value The value of the header.
+     */
+    static addHeader(name: string, value: string): void;
+    /**
+     * Sets the HTTP status code for the response.
+     * @param status The integer status code (e.g., 200, 404).
+     */
+    static setStatus(status: number): void;
+    /**
+     * Clears all buffers, status code, and headers from the response, allowing a new response to be generated.
+     * This is only possible if the response has not yet been committed.
+     */
+    static reset(): void;
+    /**
+     * Gets the value of a specific header. If multiple headers with the same name exist, it returns the first one.
+     * @param name The name of the header.
+     * @returns The header value string.
+     */
+    static getHeader(name: string): string;
+    /**
+     * Sets the locale for the response, which may affect language and date/time formatting.
+     * @param language The language code (e.g., 'en', 'fr').
+     * @param country The optional country code (e.g., 'US', 'GB').
+     * @param variant The optional variant code.
+     */
+    static setLocale(language: string, country?: string, variant?: string): void;
+    /**
+     * Gets all header values for a specific header name as an array of strings.
+     * @param name The name of the header.
+     * @returns An array of header values.
+     */
+    static getHeaders(name: string): string[];
+    /**
+     * Gets the names of all headers that have been set on the response.
+     * @returns An array of header names.
+     */
+    static getHeaderNames(): string[];
+    /**
+     * Gets the currently set locale string for the response.
+     * @returns The locale string.
+     */
+    static getLocale(): string;
+    /**
+     * Gets the underlying output stream object, wrapped in the SDK's `OutputStream` class.
+     * This is useful for writing raw or large amounts of data.
+     * @returns The output stream object.
+     */
+    static getOutputStream(): OutputStream;
+}

package/dist/dts/http/rs/resource-common.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Commmon function for initializng the callback functions in the ResourceMethod instances.
+ *
+ * @param thiz The ResourceMethod instance to which the function is bound (or Resource instance in the case of redirect).
+ * @param configuration The configuration object where the handler will be attached.
+ * @param sHandlerFuncName The name of the function that will be attached to the resource mappings configuration (e.g., 'serve', 'redirect').
+ * @param fHandler The handler function or value that will be attached to the resource mappings configuration.
+ * @returns The instance passed in as 'thiz' for method chaining.
+ * @private
+ */
+export declare function handlerFunction(thiz: any, configuration: any, sHandlerFuncName: string, fHandler: Function | string): any;

package/dist/dts/http/rs/resource-http-controller.d.ts

@@ -0,0 +1,43 @@
+import { ResourceMappings } from "./resource-mappings";
+/**
+ * Creates a service (HttpController) instance, optionally initialized with oMappings.
+ *
+ * @param oConfig Configuration object or configuration builder with configuration() getter function.
+ * @returns A new HttpController instance.
+ */
+export declare function service(oConfig?: any): HttpController;
+/**
+ * The main class for handling HTTP requests and routing them to the correct resource handlers.
+ */
+export declare class HttpController {
+    resource: Function;
+    resourcePath: Function;
+    resourceMappings: ResourceMappings;
+    [key: string]: any;
+    /**
+     * Constructor function for HttpController instances.
+     *
+     * @param oMappings The mappings configuration for this controller.
+     */
+    constructor(oMappings?: ResourceMappings | any);
+    /**
+     * Alias for execute.
+     */
+    listen(request: any, response: any): void;
+    /**
+     * Executes the request handling logic, finding the best matching resource and handler.
+     */
+    execute(request?: any, response?: any): void;
+    /**
+     * Returns the ResourceMappings instance of this controller.
+     */
+    mappings(): ResourceMappings;
+    /**
+     * Sends an error response to the client, formatted based on the accepted media type.
+     */
+    sendError(httpErrorCode: number, applicationErrorCode: any, errorName: string, errorDetails: string): void;
+    /**
+     * Flushes and closes the HTTP response stream.
+     */
+    closeResponse(): void;
+}

package/dist/dts/http/rs/resource-mappings.d.ts

@@ -0,0 +1,70 @@
+import { Resource } from "./resource";
+/**
+ * The ResourceMappings class abstracts the mappings between resource URL path templates
+ * and their corresponding resource handler specifications. It acts as the configuration
+ * store for the HttpController.
+ */
+export declare class ResourceMappings {
+    resources: {
+        [key: string]: any;
+    };
+    controller: any;
+    execute: any;
+    /**
+     * Constructor function for ResourceMappings instances.
+     *
+     * @param oConfiguration Configuration object defining initial resource paths and their handlers.
+     * @param controller The HttpController instance, for which this ResourceMappings handles configuration.
+     */
+    constructor(oConfiguration: any, controller: any);
+    /**
+     * Creates or retrieves a Resource object corresponding to the given path.
+     * The second, optional argument can be used to initialize the resource.
+     *
+     * @param sPath The URL path template for the resource (e.g., "users/{id}").
+     * @param oConfiguration Optional configuration object for initial resource setup.
+     * @returns The created or existing Resource instance.
+     */
+    path(sPath: string, oConfiguration?: any): Resource;
+    /**
+     * Alias for path().
+     */
+    resourcePath(sPath: string, oConfiguration?: any): Resource;
+    /**
+     * Alias for path().
+     */
+    resource(sPath: string, oConfiguration?: any): Resource;
+    /**
+     * Returns the compiled configuration object for all resources managed by this ResourceMappings.
+     * The configuration is structured to be consumed by the HttpController's routing logic.
+     */
+    configuration(): {
+        [key: string]: any;
+    };
+    /**
+     * Removes all but GET resource handlers from all managed resources, making them read-only.
+     *
+     * @returns The ResourceMappings instance for method chaining.
+     */
+    readonly(): this;
+    /**
+     * Disables resource handling specifications matching the arguments, effectively removing them from this API.
+     *
+     * @param sPath The path of the resource.
+     * @param sVerb The HTTP verb (e.g., 'get', 'post').
+     * @param arrConsumes Array of consumed media types.
+     * @param arrProduces Array of produced media types.
+     * @returns The ResourceMappings instance for method chaining.
+     */
+    disable(sPath: string, sVerb: string, arrConsumes: string[], arrProduces: string[]): this;
+    /**
+     * Provides a reference to a handler specification matching the supplied arguments.
+     *
+     * @param sPath The path of the resource.
+     * @param sVerb The HTTP verb (e.g., 'get', 'post').
+     * @param arrConsumes Array of consumed media types.
+     * @param arrProduces Array of produced media types.
+     * @returns The matching Resource handler specification or undefined.
+     */
+    find(sPath: string, sVerb: string, arrConsumes: string[], arrProduces: string[]): any | undefined;
+}

package/dist/dts/http/rs/resource-method.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Interface for the internal configuration object of a ResourceMethod.
+ */
+interface ResourceMethodConfig {
+    consumes?: string[];
+    produces?: string[];
+    before?: Function;
+    serve?: Function;
+    catch?: Function;
+    finally?: Function;
+    [key: string]: any;
+}
+/**
+ * Constructor function for ResourceMethod instances.
+ * This class handles the fluent configuration for a single HTTP method handler (e.g., GET)
+ * attached to a Resource.
+ *
+ * /**
+ * Constructor function for ResourceMethod instances.
+ * All parameters of the function are optional.
+ *
+ * Providing oConfiguration will initialize this instance with some initial configuration instead of starting
+ * entirely from scratch. Note that the configuration object schema must be compliant with the one produced by
+ * the ResourceMethod itself. If this parameter is omited, setup will start from scratch.
+ *
+ * Provisioning controller, will inject a reference to the execute method of the controller so that it can be
+ * fluently invoked in the scope of this ResourceMehtod instance as part of the method chaining flow. The execute
+ * function scope is bound to the controller instance for this ResourceMethod.
+ *
+ * @example
+ * ```js
+ * rs.service()
+ *  .resource('')
+ * 		.get()
+ * 	.execute();
+ * ```
+ *
+ * Provisioning resource, will inject a reference ot the HTTP method functions of the Resource class (get, post,
+ * put, delete, remove, method) so that they can be fluently invoked in the scope of this ResourceMethod instance
+ * as part of the method chaining flow. The functions are bound to the resource instance for this ResourceMethod.
+ *
+ * @example
+ * ```js
+ * rs.service()
+ *  .resource('')
+ * 		.get(function(){})
+ * 		.post(function(){})
+ * 		.put(function(){})
+ * 		.remove(function(){})
+ * .execute();
+ * ```
+ *
+ * Provisioning mappings, will inject a reference ot the resource method of the ResourceMappings class so that
+ * it can be fluently invoked in the scope of this ResourceMethod instance as part of the method chaining flow.
+ * The function is bound to the mappings instance for this ResourceMethod.
+ *
+ * @example
+ * ```js
+ * rs.service()
+ *  .resource('')
+ * 		.get(function(){})
+ * 	.resource('{id}')
+ * 		.get(function(){})
+ * .execute();
+ * ``
+ *
+ */
+export declare class ResourceMethod {
+    cfg: ResourceMethodConfig;
+    _resource: any;
+    controller: any;
+    resource: Function;
+    resourcePath: Function;
+    path: Function;
+    /**
+     * @param oConfiguration Initial configuration object.
+     * @param controller The HttpController instance.
+     * @param resource The parent Resource instance.
+     * @param mappings The parent ResourceMappings instance.
+     * @returns {ResourceMethod}
+     */
+    constructor(oConfiguration: any, controller: any, resource: any, mappings: any);
+    /**
+     * Delegates to the HttpController's execute function to process the request.
+     */
+    execute(): void;
+    /**
+     * Delegates to the parent Resource's 'get' method.
+     */
+    get(): any;
+    /**
+     * Delegates to the parent Resource's 'post' method.
+     */
+    post(): any;
+    /**
+     * Delegates to the parent Resource's 'put' method.
+     */
+    put(): any;
+    /**
+     * Delegates to the parent Resource's 'delete' method.
+     */
+    delete(): any;
+    /**
+     * Delegates to the parent Resource's 'remove' method.
+     */
+    remove(): any;
+    /**
+     * Delegates to the parent Resource's 'method' method.
+     */
+    method(): any;
+    /**
+     * Returns the configuration object for this ResourceMethod instance.
+     *
+     * @returns The configuration object.
+     */
+    configuration(): ResourceMethodConfig;
+    /**
+     * Applies a callback function for the **before** phase of processing a matched resource request.
+     *
+     * @param fHandler Callback function for the before phase.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    before(fHandler: Function): ResourceMethod;
+    /**
+     * Applies a callback function for processing a matched resource request (**serve** phase).
+     *
+     * @param fHandler Callback function for the serve phase.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    serve(fHandler: Function): ResourceMethod;
+    /**
+     * Applies a callback function for the **catch** errors phase of processing a matched resource request.
+     *
+     * @param fHandler Callback function for the catch phase.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    catch(fHandler: Function): ResourceMethod;
+    /**
+     * Applies a callback function for the **finally** phase of processing a matched resource request.
+     *
+     * @param fHandler Callback function for the finally phase.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    finally(fHandler: Function): ResourceMethod;
+    /**
+     * Defines the content MIME type(s), which this ResourceMethod expects as input (**consumes**).
+     *
+     * @param mimeTypes Sets the mime types that this ResourceMethod is capable to consume.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    consumes(mimeTypes: string | string[]): ResourceMethod;
+    /**
+     * Defines the HTTP response payload MIME type(s), which this ResourceMethod request processing function outputs, i.e.
+     * those that it 'produces'. At runtime, the Accept request header will be matched for compatibility with this setting
+     * to elicit request processing functions.
+     * Note that the matching is performed by compatibility, not strict equality, i.e. the MIME type format wildcards are
+     * considered too. For example, a request Accept header "*\/json" will match a produces setting "application\/json".
+     *
+     * @example
+     * ```js
+     * rs.service()
+     *	.resource("")
+     * 		.get(function(){})
+     * 			.produces(["application\/json"])
+     * .execute();
+     * 	.
+     * ```
+     *
+     * Take care to make sure that the produces constraint correctly describes the response contenty MIME types that the request
+     * processing function can produce so that only client request that can accept them land there.
+     *
+     * A note about method argument multiplicity (string vs array of strings).
+     * One of the arguments of the produce method will translate to the response Content-Type property, which is known to be a
+     * single value header by [specification](https://tools.ietf.org/html/rfc7231#section-3.1.1.5). There are two reasons why
+     * the method accepts array and not a single value only:
+     *
+     * 1. Normally, when matched, content types are evaluated for semantic compatibility and not strict equality on both sides
+     *  - client and server. Providing a range of compatible MIME types instead of single value, increases the range of acceptable
+     * requests for procesing, while reducing the stricness of the requirements on the client making the request. For example,
+     * declaring ["text/json,"application/json"] as produced types makes requests with any of these accept headers (or a combination
+     * of them) acceptable for processing: "*\/json", "text/json", "application/json", "*\/*".
+     *
+     * 2. Although in most cases a handler function will produce payload in single format (media type), it is quite possible to
+     * desgin it also as a controller that produces alternative payload in different formats. In these cases you need produces
+     * that declares all supported media types so that the request with a relaxed Accept header matching any of them can land
+     * in this function. That makes the routing a bit less transparent and dependent on the client, but may prove valuable for
+     * certian cases.
+     *
+     * In any case it is responsibility of the request processing function to set the correct Content-Type header.
+     *
+     * @param mimeTypes Sets the mime type(s) that this ResourceMethod may produce.
+     * @returns The ResourceMethod instance for method chaining.
+     */
+    produces(mimeTypes: string | string[]): ResourceMethod;
+    /**
+     * Commmon function for initializng the 'consumes' and 'produces' arrays in the ResourceMethod instances.
+     * Before finalizing the configuration setup the function will remove duplicates with exact match filtering.
+     *
+     * @param mimeSettingName must be either 'consumes' or 'produces'.
+     * @param mimeTypes An array of strings formatted as mime types (type/subtype) or a single string.
+     * @returns The ResourceMethod instance to which the function is bound.
+     * @private
+     */
+    private mimeSetting;
+}
+export {};