sprucehttp_sjs 2.0.0 → 2.2.0

package/README.md

@@ -10,6 +10,7 @@ A module for responding to requests within SpruceHTTP in an SJS file.
 	- [writeData(data)](#writedatadata)
 	- [writeDataAsync(data)](#writedataasyncdata)
 	- [clearResponse()](#clearresponse)
+	- [end()](#end)
 	- [siteConfig](#siteconfig)
 	- [requestIP](#requestip)
 	- [method](#method)
@@ -23,6 +24,9 @@ A module for responding to requests within SpruceHTTP in an SJS file.
 	- [body](#body)
 	- [bodyStream([options])](#bodystreamoptions)
 	- [mTlsPeerCertificate](#mtlspeercertificate)
+	- [requestObject](#requestobject)
+	- [updateConfig(newConfig)](#updateconfignewconfig)
+	- [modifyRequest(newRequest)](#modifyrequestnewrequest)
 
 ## Documentation:
 Importing the module:
@@ -35,8 +39,10 @@ Sets the response into stream mode. This cannot be undone for the duration of th
 
 Stream mode means that responses are not buffered by the webserver, and thus are sent immediately as they're received from the SJS script. This means that the status line and headers _**must**_ be sent first before the data, and the ``\r\n`` after the headers must be sent by the script as well.
 
+Returns a Promise that resolves when the server acknowledges the switch to stream mode.
+
 ```js
-sjs.streamMode(); // Set the response to stream mode.
+await sjs.streamMode(); // Set the response to stream mode.
 ```
 
 ### ``writeStatusLine(statusCode[, reasonPhrase])``:
@@ -45,14 +51,16 @@ sjs.streamMode(); // Set the response to stream mode.
 
 Writes the status line to the response.
 
+Returns a Promise that resolves when the server acknowledges the status line.
+
 To send a 200 "OK" response, without needing to specify the reason phrase.
 ```js
-sjs.writeStatusLine(200);
+await sjs.writeStatusLine(200);
 ```
 
 To send a 418 "I'm a teapot" response, with a specified reason phrase.
 ```js
-sjs.writeStatusLine(418, "I'm a teapot");
+await sjs.writeStatusLine(418, "I'm a teapot");
 ```
 
 ### ``writeHeader(name, value)``:
@@ -61,9 +69,11 @@ sjs.writeStatusLine(418, "I'm a teapot");
 
 Writes a header to the response.
 
+Returns a Promise that resolves when the server acknowledges the header.
+
 To write the "Content-Type: text/html" header.
 ```js
-sjs.writeHeader("Content-Type", "text/html");
+await sjs.writeHeader("Content-Type", "text/html");
 ```
 
 ### ``writeData(data)``:
@@ -89,6 +99,8 @@ sjs.writeData(fs.readFileSync("image.png", 'binary'));
 
 Writes data (the body) to the response asynchronously. When not in stream mode, the Content-Length header is automatically updated.
 
+Returns a Promise that resolves when the data has been written.
+
 Writes text data to the body.
 ```js
 await sjs.writeDataAsync("Hello, world!");
@@ -104,23 +116,40 @@ await sjs.writeDataAsync(fs.readFileSync("image.png", 'binary'));
 Clears the currently written response and resets the status line, headers, and body.
 This is useful when you want to send a different response than the one you have already written.
 
+Returns a Promise that resolves when the response has been cleared.
+
 This function does not work in stream mode.
 
 ```js
-sjs.writeStatusLine(418, "I'm a teapot");
-sjs.writeHeader("Content-Type", "text/html");
-sjs.writeData("<h1>I'm a teapot</h1>");
+await sjs.writeStatusLine(418, "I'm a teapot");
+await sjs.writeHeader("Content-Type", "text/html");
+await sjs.writeData("<h1>I'm a teapot</h1>");
 // Be serious
-sjs.clearResponse();
+await sjs.clearResponse();
 
-sjs.writeStatusLine(200);
-sjs.writeHeader("Content-Type", "text/html");
-sjs.writeData("<h1>I'm <i>not</i> a teapot</h1>");
+await sjs.writeStatusLine(200);
+await sjs.writeHeader("Content-Type", "text/html");
+await sjs.writeData("<h1>I'm <i>not</i> a teapot</h1>");
+```
+
+### ``end()``:
+Ends the response. Responses are automatically ended when the SJS script exits, but this function allows you to end the response early. This is useful if you want to stop sending data before the script has finished executing.
+
+Returns a Promise that resolves when the response has been ended.
+
+```js
+await sjs.writeStatusLine(200);
+await sjs.writeHeader("Content-Type", "text/html");
+await sjs.writeData("<h1>Hello, world!</h1>");
+await sjs.end(); // End the response early
+// Any further writes will be ignored
 ```
 
 ### ``siteConfig``:
 Returns the site-specific configuration set in your config file.
 
+Returns an object representing the site configuration.
+
 ```js
 console.log(sjs.siteConfig);
 /*
@@ -148,7 +177,7 @@ Returns the requestor's IP address.
 
 ```js
 console.log(sjs.requestIP);
-// ::ffff:127.0.0.1
+// ::ffff:198.51.100.163
 ```
 
 ### ``method``:
@@ -257,4 +286,45 @@ Returns details about the mTLS peer's certificate, if present.
 ```js
 console.log(sjs.mTlsPeerCertificate.subject.CN);
 // sprucehttp.com
+```
+
+### ``requestObject``:
+Returns the full request object.
+
+```js
+console.log(sjs.requestObject);
+// {
+//     "version": "HTTP/1.1",
+//     ... rest of request object ...
+// }
+```
+
+### ``updateConfig(newConfig)``:
+ - ``newConfig:`` object: The new site configuration to set.
+
+Updates the site-specific configuration for the request. You must provide a complete configuration object.
+
+This is only effective during a pre-request hook.
+
+Returns a Promise that resolves when the configuration has been updated.
+
+```js
+sjs.updateConfig({
+	// New configuration object
+});
+```
+
+### ``modifyRequest(newRequest)``:
+ - ``newRequest:`` object: The new request object to set.
+
+Modifies the request object for the request. You must provide a complete request object.
+
+This is only effective during a pre-request hook.
+
+Returns a Promise that resolves when the request has been modified.
+
+```js
+sjs.modifyRequest({
+	// New request object
+});
 ```

package/index.js

@@ -1,16 +1,37 @@
 // This is still CommonJS to support both the old and new versions of the module system.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const fs = require("fs");
+const fs = require("node:fs");
+
+/**
+ * Wait until the server tells us that it has processed the last sent message.
+ * 
+ * @returns {Promise<void>} A Promise that resolves when the server has processed the last message.
+ */
+function waitUntilProcessed() {
+	return new Promise(function (resolve) {
+		process.once("message", function (message) {
+			if (message === "ready") {
+				resolve();
+			}
+		});
+	});
+}
 
 module.exports = {
 	/**
 	 * Sets the response into stream mode.
 	 * 
 	 * Stream mode means that responses are not buffered by the webserver.
+	 * @returns {Promise<void>} A Promise that resolves when the server acknowledges the switch to stream mode.
 	 */
 	streamMode() {
-		process.send({
-			type: "streamMode"
+		return new Promise(function (resolve) {
+			process.send({
+				type: "streamMode"
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -18,12 +39,18 @@ module.exports = {
 	 * Writes the status line to the response.
 	 * @param {number} statusCode The HTTP status code to send.
 	 * @param {string} [reasonPhrase] The reason phrase to send.
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the status line.
 	 */
 	writeStatusLine(statusCode, reasonPhrase) {
-		process.send({
-			type: "status",
-			statusCode,
-			reasonPhrase
+		return new Promise(function (resolve) {
+			process.send({
+				type: "status",
+				statusCode,
+				reasonPhrase
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -31,12 +58,18 @@ module.exports = {
 	 * Writes a header to the response.
 	 * @param {string} name The name of the header to send.
 	 * @param {string} value The value of the header to send.
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the header.
 	 */
 	writeHeader(name, value) {
-		process.send({
-			type: "header",
-			name,
-			value
+		return new Promise(function (resolve) {
+			process.send({
+				type: "header",
+				name,
+				value
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -45,7 +78,8 @@ module.exports = {
 	 * 
 	 * When not in stream mode, the Content-Length header is automatically updated.
 	 * @param {string | Buffer} data The data to send.
-	 * @deprecated Use writeDataAsync instead. Data cannot be reliably sent synchronously.
+	 * @returns {void}
+	 * @deprecated Use writeDataAsync instead. Data cannot be reliably sent synchronously. Will be removed in a future major version.
 	 */
 	writeData(data) {
 		(async () => { await this.writeDataAsync(data); })();
@@ -54,8 +88,11 @@ module.exports = {
 	/**
 	 * Writes data (the body) to the response asynchronously.
 	 * 
+	 * Will be renamed to writeData in a future major version.
+	 * 
 	 * When not in stream mode, the Content-Length header is automatically updated.
 	 * @param {string | Buffer} data The data to send.
+	 * @returns {Promise<void>} A Promise that resolves when the data has been written.
 	 */
 	writeDataAsync(data) {
 		// eslint-disable-next-line no-async-promise-executor
@@ -74,7 +111,10 @@ module.exports = {
 					process.send({
 						type: "data",
 						data: chunk
-					}, resolve2);
+					}, async () => {
+						await waitUntilProcessed();
+						resolve2();
+					});
 				});
 			}
 			resolve();
@@ -86,17 +126,38 @@ module.exports = {
 	 * This is useful when you want to send a different response than the one you have already written.
 	 * 
 	 * This function does not work in stream mode.
+	 * @returns {Promise<void>} A Promise that resolves when the response has been cleared.
 	 */
 	clearResponse() {
-		process.send({
-			type: "clear"
+		return new Promise(function (resolve) {
+			process.send({
+				type: "clear"
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
+		});
+	},
+
+	/**
+	 * Ends the response. This will not terminate the SJS script; it will continue to run until completion.
+	 * @returns {Promise<void>}
+	 */
+	end() {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "end"
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
 	/**
 	 * Returns the site-specific configuration.
 	 * 
-	 * @returns {{[key: string]: string}} The site-specific configuration.
+	 * @returns {import("./types").SiteConfig} The site-specific configuration.
 	 */
 	get siteConfig() {
 		return JSON.parse(process.env.siteConfig);
@@ -201,7 +262,7 @@ module.exports = {
 	/**
 	 * Returns the body of the request as an fs.ReadStream.
 	 * 
-	 * @param {BufferEncoding | ReadStreamOptions} [options] The options to pass to fs.createReadStream.
+	 * @param {BufferEncoding | fs.ReadStreamOptions} [options] The options to pass to fs.createReadStream.
 	 * @returns {fs.ReadStream} A ReadStream of the body of the request.
 	 */
 	bodyStream(options) {
@@ -215,7 +276,7 @@ module.exports = {
 	/**
 	 * Returns details about the mTLS peer's certificate, if present.
 	 * 
-	 * @returns {PeerCertificate}
+	 * @returns {import("node:tls").PeerCertificate}
 	 */
 	get mTlsPeerCertificate() {
 		let retVal = undefined;
@@ -225,5 +286,52 @@ module.exports = {
 			if (retVal.pubkey) retVal.pubkey = Buffer.from(retVal.pubkey, "base64");
 		}
 		return retVal;
+	},
+
+	/**
+	 * Returns the full request object.
+	 * 
+	 * @returns {import("./types").HTTPRequest} The full request object.
+	 */
+	get requestObject() {
+		return JSON.parse(process.env.requestObject);
+	},
+
+	/**
+	 * Updates the site-specific configuration for the request. You must provide a complete configuration object.
+	 * 
+	 * This is only effective during a pre-request hook.
+	 * @param {import("./types").SiteConfig} newConfig The new site configuration to set.
+	 * @return {Promise<void>} A Promise that resolves when the configuration has been updated.
+	 */
+	updateConfig(newConfig) {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "siteconfigmodify",
+				siteConfig: newConfig
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
+		});
+	},
+
+	/**
+	 * Modifies the request object. You must provide a complete request object.
+	 * 
+	 * This is only effective during a pre-request hook.
+	 * @param {import("./types").HTTPRequest} newRequest The new request object to set.
+	 * @return {Promise<void>} A Promise that resolves when the request has been modified.
+	 */
+	modifyRequest(newRequest) {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "requestmodify",
+				request: newRequest
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
+		});
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sprucehttp_sjs",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "A module for responding to requests within SpruceHTTP in an SJS file",
 	"main": "index.js",
 	"scripts": {

package/types.ts

@@ -0,0 +1,156 @@
+import { TlsOptions } from "node:tls";
+
+/**
+ * Represents a site configuration.
+ * @property {string} type The type of configuration.
+ * @property {string} location The path to the root of the site.
+ * @property {string[]} [indexList] The list of files to check for when serving a directory.
+ * @property {boolean} [upgradeInsecure] Require HTTPS for all requests.
+ * @property {boolean} [directoryListing] Whether to serve directory listings.
+ * @property {number} [maxBodySize] The maximum body size in bytes to accept.
+ * @property {boolean} [sjs] Whether to execute SJS files.
+ * @property {Record<string, string>} [headers] The headers to send with the response.
+ * @property {TlsOptions} [ssl] The TLS options to use.
+ * @property {boolean} [trustProxy] Whether the site trusts the proxy (X-Forwarded-For).
+ * @property {boolean} [compress] Whether to compress the response.
+ * @property {string[]} [mimesToCompress] The list of MIME types to compress.
+ * @property {boolean} [excludeFromLogging] Whether to exclude this site from access logs.
+ * @property {string[]} [preRequestHooks] An array of paths to pre-request hook scripts for this site.
+ */
+interface LocalSiteConfig {
+	type: "local";
+	location: string;
+	indexList: string[];
+	upgradeInsecure: boolean;
+	directoryListing: boolean;
+	maxBodySize: number;
+	sjs: boolean;
+	headers: Record<string, string>;
+	ssl: TlsOptions;
+	trustProxy: boolean;
+	compress: boolean;
+	mimesToCompress: string[];
+	excludeFromLogging: boolean;
+	preRequestHooks: string[];
+}
+
+/**
+ * Represents a remote site configuration.
+ * @property {string} type The type of configuration.
+ * @property {string | string[]} location The URL or URLs of the target server. The request path will be appended to this. If multiple locations are provided, one will be chosen at random.
+ * @property {boolean} upgradeInsecure Require HTTPS for all requests.
+ * @property {number} maxBodySize The maximum body size in bytes to accept.
+ * @property {Record<string, string>} headers The headers to send with the response.
+ * @property {TlsOptions} ssl The TLS options to use when connecting to the target.
+ * @property {boolean} trustProxy Whether the site trusts the proxy (X-Forwarded-For).
+ * @property {boolean} preserveHost Whether to preserve the original host header (true), or rewrite it (false; default)
+ * @property {boolean} allowInsecure Whether to allow insecure TLS connections to the target (self-signed certificates, etc).
+ * @property {string} errorPagesLocation The location to find custom error pages for this site.
+ * @property {boolean} excludeFromLogging Whether to exclude this site from access logs.
+ */
+interface RemoteSiteConfig {
+	type: "remote";
+	location: string | string[];
+	upgradeInsecure: boolean;
+	maxBodySize: number;
+	headers: Record<string, string>;
+	ssl: TlsOptions;
+	trustProxy: boolean;
+	preserveHost: boolean;
+	allowInsecure: boolean;
+	errorPagesLocation: string;
+	excludeFromLogging: boolean;
+}
+
+type SiteConfig = LocalSiteConfig | RemoteSiteConfig;
+
+enum HTTP_VERSION {
+	HTTP0_9 = "HTTP/0.9",
+	HTTP1_0 = "HTTP/1.0",
+	HTTP1_1 = "HTTP/1.1",
+	HTTP2_0 = "HTTP/2.0",
+	HTTP3_0 = "HTTP/3.0"
+}
+
+enum HTTP_METHOD {
+	GET = "GET",
+	HEAD = "HEAD",
+	POST = "POST",
+	PUT = "PUT",
+	DELETE = "DELETE",
+	CONNECT = "CONNECT",
+	OPTIONS = "OPTIONS",
+	TRACE = "TRACE",
+	PATCH = "PATCH",
+	OTHER = "OTHER"
+}
+
+type HTTPRequest = {
+	/**
+	 * The HTTP version.
+	 */
+	version: HTTP_VERSION;
+
+	/**
+	 * The HTTP method.
+	 */
+	method: HTTP_METHOD;
+
+	/**
+	 * The path of the request.
+	 */
+	path: string;
+
+	/**
+	 * The parameters of the request.
+	 */
+	params: Record<string, string>;
+
+	/**
+	 * The headers of the request.
+	 */
+	headers: Record<string, string>;
+	
+	/**
+	 * The body of the request.
+	 * This parameter is a path to a temporary file containing the body.
+	 */
+	body?: string;
+
+	/**
+	 * The session ID.
+	 */
+	session?: string;
+
+	/**
+	 * The remote family (IPv4 or IPv6).
+	 */
+	remoteFamily: string;
+
+	/**
+	 * The remote address.
+	 */
+	remoteAddress: string;
+
+	/**
+	 * The remote port.
+	 */
+	remotePort: number;
+
+	/**
+	 * The protocol used (http or https).
+	 */
+	protocol: "http" | "https";
+
+	/**
+	 * Whether the connection should be kept alive.
+	 */
+	keepAlive: boolean;
+
+	/**
+	 * Request ID for logging and tracing.
+	 */
+	requestId: string;
+}
+
+export { SiteConfig, HTTPRequest };