sprucehttp_sjs 2.1.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:
@@ -38,7 +42,7 @@ Stream mode means that responses are not buffered by the webserver, and thus are
 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])``:
@@ -51,12 +55,12 @@ 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)``:
@@ -69,7 +73,7 @@ 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)``:
@@ -117,15 +121,28 @@ 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``:
@@ -160,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``:
@@ -269,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

@@ -2,6 +2,21 @@
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 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.
@@ -13,7 +28,10 @@ module.exports = {
 		return new Promise(function (resolve) {
 			process.send({
 				type: "streamMode"
-			}, resolve);
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -29,7 +47,10 @@ module.exports = {
 				type: "status",
 				statusCode,
 				reasonPhrase
-			}, resolve);
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -45,7 +66,10 @@ module.exports = {
 				type: "header",
 				name,
 				value
-			}, resolve);
+			}, async () => {
+				await waitUntilProcessed();
+				resolve();
+			});
 		});
 	},
 
@@ -87,7 +111,10 @@ module.exports = {
 					process.send({
 						type: "data",
 						data: chunk
-					}, resolve2);
+					}, async () => {
+						await waitUntilProcessed();
+						resolve2();
+					});
 				});
 			}
 			resolve();
@@ -105,14 +132,32 @@ module.exports = {
 		return new Promise(function (resolve) {
 			process.send({
 				type: "clear"
-			}, resolve);
+			}, 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);
@@ -217,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) {
@@ -241,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.1.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 };