webhoster 0.1.1 → 0.3.0

package/lib/HttpResponse.js

@@ -1,111 +1,375 @@
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc7230
+ * @see https://www.rfc-editor.org/rfc/rfc7231
+ */
+
 /** @typedef {import('stream').Writable} Writable */
 
+import { PassThrough, Readable, pipeline } from 'node:stream';
+
+import { isWritable } from '../utils/stream.js';
+
 /** @typedef {import('http').OutgoingHttpHeaders} OutgoingHttpHeaders */
+/** @typedef {import('stream').Stream} Stream */
+/** @typedef {import('../types/index.js').Middleware} Middleware */
+/** @typedef {import('./HttpRequest.js').default} HttpRequest */
+/** @typedef {import('../types/index.js').ResponseFinalizer} ResponseFinalizer */
 
 /**
  * @typedef {Object} HttpResponseOptions
+ * @prop {HttpRequest} [request]
  * @prop {OutgoingHttpHeaders} [headers]
  * @prop {function():boolean} [onHeadersSent]
- * @prop {function(boolean):void} [onSendHeaders]
+ * @prop {(flush:boolean, end:boolean) => any} [onSendHeaders]
  * @prop {number} [status]
  * @prop {Writable} stream
- * @prop {import('net').Socket|import('tls').TLSSocket} [socket]
- * @prop {boolean} [canPushPath]
- * @prop {function(string):Promise<any>} [onPushPath]
- * @prop {Object<string,any>} [locals]
- * @prop {boolean} [unsealed]
+ * @prop {Stream[]} [pipes]
+ * @prop {ResponseFinalizer[]} [finalizers] inline middleware for message body
+ * @prop {any} [body]
  */
 
 export default class HttpResponse {
   /** @type {function():boolean} */
   #onHeadersSent = null;
 
-  /** @type {function(boolean):void} */
+  /** @type {(flush:boolean, end:boolean) => any} */
   #onSendHeaders = null;
 
-  /** @type {function(string):Promise<any>} */
-  #onPushPath = null;
-
-  /** @type {boolean} */
   #headersSent = false;
 
-  /** @type {Array<string>} */
-  #pushedPaths = [];
+  /** @type {Writable} */
+  #pipeline;
+
+  #pipelineComplete = false;
 
-  #canPushPath = false;
+  /** @type {Function[]} */
+  #pipelineCallbacks = [];
+
+  #endCalled = false;
 
   /** @param {HttpResponseOptions} options */
   constructor(options) {
+    this.request = options.request;
     /** @type {OutgoingHttpHeaders} */
-    this.headers = options.headers || {};
+    this.headers = options.headers ?? {};
+    this.isStreaming = false;
     this.stream = options.stream;
-    this.socket = options.socket;
+    this.pipes = options.pipes ?? [];
+    /** @type {ResponseFinalizer[]} */
+    this.finalizers = options.finalizers ?? [];
     this.status = options.status;
-    this.#onPushPath = options.onPushPath;
+    /** @type {any} */
+    this.body = options.body;
     this.#onHeadersSent = options.onHeadersSent;
     this.#onSendHeaders = options.onSendHeaders;
-    this.#canPushPath = options.canPushPath ?? false;
-    this.locals = options.locals || {};
-    this.unsealed = options.unsealed ?? false;
-    if (!this.unsealed) {
-      Object.seal(this);
-    }
   }
 
-  get headersSent() {
-    if (this.#onHeadersSent) {
-      return this.#onHeadersSent();
-    }
-    return this.#headersSent;
+  get statusCode() {
+    return this.status;
+  }
+
+  set statusCode(number) {
+    this.status = number;
   }
 
   /**
-   * @param {Writable} stream
-   * @return {Writable} previousStream
+   * A boolean indicating whether the response was successful (status in the range 200–299) or not.
+   * @return {boolean}
    */
-  replaceStream(stream) {
-    const previousStream = this.stream;
-    this.stream = stream;
-    return previousStream;
+  get ok() {
+    return this.status >= 200 && this.status <= 299;
+  }
+
+  get headersSent() {
+    if (this.#headersSent) return true;
+    if (!this.#onHeadersSent) return false;
+    return this.#onHeadersSent();
   }
 
   /**
-   * @param {boolean} [flush]
+   * @param {boolean} [flush] Flush headers
+   * @param {boolean} [end] End stream
    * @return {void}
    */
-  sendHeaders(flush) {
+  sendHeaders(flush, end) {
     if (this.headersSent) {
-      throw new Error('ALREADY_SENT');
+      throw new Error('HEADER_SENT');
     }
     if (!this.#onSendHeaders) {
       throw new Error('NOT_IMPLEMENTED');
     }
-    this.#onSendHeaders(flush);
+    this.#onSendHeaders(flush, end);
     this.#headersSent = true;
   }
 
-  get pushedPaths() {
-    return this.#pushedPaths;
+  /**
+   * @param {number} [status]
+   * @return {Promise<0>} HttpHandler.END
+   */
+  async sendStatusOnly(status) {
+    if (this.headersSent) throw new Error('ERR_HEADER_SENT');
+    if (!isWritable(this.stream)) throw new Error('NOT_WRITABLE');
+    if (status) {
+      this.status = status;
+    }
+    await this.sendHeaders(true, true);
+    return 0;
+  }
+
+  /**
+   * Send message body to response stream without finalizers
+   * @param {any} [body]
+   * @return {Promise<0>}
+   */
+  async sendRaw(body) {
+    this.body = body;
+    await new Promise((resolve, reject) => {
+      this.stream.end(body, (err) => (err ? reject(err) : resolve()));
+    });
+    return 0;
   }
 
-  get canPushPath() {
-    return this.#canPushPath;
+  /** @return {boolean} */
+  hasPipeline() {
+    return this.#pipeline != null;
+  }
+
+  /**
+   * @param {Transform} stream
+   * @return {this}
+   */
+  addUpstream(stream) {
+    this.pipes.push(stream);
+    return this;
   }
 
   /**
-   * @param {string} [path]
-   * @return {Promise<any>}
+   * @param {(err: NodeJS.ErrnoException | null) => void} [callback] pipeline completion
+   * @return {Writable}
    */
-  pushPath(path) {
-    if (this.#pushedPaths.includes(path)) {
-      return Promise.reject(new Error('ALREADY_PUSHED'));
+  getPipeline(callback) {
+    if (callback) {
+      if (this.#pipelineComplete) {
+        setTimeout(callback, 0);
+      } else {
+        this.#pipelineCallbacks.push(callback);
+      }
     }
-    if (!this.#onPushPath) {
-      return Promise.reject(new Error('NOT_IMPLEMENTED'));
+
+    if (this.#pipeline) return this.#pipeline;
+
+    if (!this.isStreaming) {
+      // Called directly by user and needs finalizer calls
+
+      this.isStreaming = true;
+      for (let i = 0; i < this.finalizers.length; i++) {
+        const process = this.finalizers[i];
+        const result = process(this);
+        if (result === false) {
+          break;
+        }
+      }
     }
-    if (!this.#canPushPath) {
-      return Promise.reject(new Error('NOT_SUPPORTED'));
+    let array;
+    if (this.pipes.length) {
+      array = [
+        ...this.pipes,
+        this.stream,
+      ];
+    } else {
+      array = [
+        new PassThrough({ objectMode: true }),
+        this.stream,
+      ];
     }
-    return this.#onPushPath(path);
+
+    this.#pipeline = array[0];
+    // @ts-ignore Bad typings
+    pipeline(array, (err) => {
+      this.#pipelineComplete = true;
+      let nextCallback;
+      while ((nextCallback = this.#pipelineCallbacks.shift()) != null) {
+        nextCallback(err);
+      }
+    });
+    return this.#pipeline;
+  }
+
+  /**
+   * Asynchronously sends message body
+   * Returns on completions
+   * @throws {Error}
+   * @param {any} [body]
+   * @return {Promise<0>} HttpHandler.END
+   */
+  async send(body) {
+    if (!isWritable(this.stream)) throw new Error('NOT_WRITABLE');
+    if (this.isStreaming) throw new Error('ALREADY STREAMING');
+
+    if (body !== undefined) {
+      this.body = body;
+    }
+    if (this.body instanceof Readable) {
+      this.isStreaming = true;
+      this.pipes.push(this.body);
+    }
+
+    for (const process of this.finalizers) {
+      const result = process(this);
+      if (result === true || result == null) {
+        continue;
+      }
+      if (result === false) {
+        break;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      const promiseResult = await result;
+      if (promiseResult === true || result == null) {
+        continue;
+      }
+      if (promiseResult === false) {
+        break;
+      }
+    }
+    if (!isWritable(this.stream)) return 0;
+    if (this.isStreaming) {
+      await new Promise((resolve, reject) => {
+        this.getPipeline((err) => {
+          if (err) reject(err);
+          resolve();
+        });
+      });
+    } else {
+      if (!this.headersSent) this.sendHeaders();
+      await this.sendRaw(this.body);
+    }
+    return 0;
+  }
+
+  wasEndCalled() {
+    return this.#endCalled;
+  }
+
+  /**
+   * Synchronously ends stream with message body. Ignores errors
+   * @param {any} [body]
+   * @return {0} HttpHandler.END
+   */
+  end(body) {
+    this.#endCalled = true;
+    if (!isWritable(this.stream)) {
+      return 0;
+    }
+    if (this.isStreaming) {
+      throw new Error('ALREADY STREAMING');
+    }
+
+    if (body !== undefined) {
+      this.body = body;
+    }
+
+    if (this.body instanceof Readable) {
+      this.isStreaming = true;
+      this.pipes.push(this.body);
+    }
+
+    // Process
+    /** @type {ResponseFinalizer[]} */
+    const pendingProcessors = [];
+    let needsAsync = false;
+    /** @type {void|Promise<boolean|void>} */
+    let pendingPromise;
+    let i;
+    for (i = 0; i < this.finalizers.length; i++) {
+      const process = this.finalizers[i];
+      if (needsAsync) {
+        pendingProcessors.push(process);
+        continue;
+      }
+
+      const result = process(this);
+      if (result === true || result == null) {
+        continue;
+      }
+      if (result === false) {
+        break;
+      }
+      pendingPromise = result;
+      needsAsync = true;
+      continue;
+    }
+    if (pendingPromise) {
+      pendingPromise.then(async (initialResult) => {
+        if (initialResult !== false) {
+          for (i = 0; i < pendingProcessors.length; i++) {
+            const process = pendingProcessors[i];
+            const result = process(this);
+            if (result === true || result == null) {
+              continue;
+            }
+            if (result === false) {
+              break;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            const promiseResult = await result;
+            if (promiseResult === true || result == null) {
+              continue;
+            }
+            if (promiseResult === false) {
+              break;
+            }
+          }
+        }
+
+        if (this.isStreaming) {
+          this.getPipeline();
+        } else {
+          if (!this.headersSent) this.sendHeaders();
+          if (this.body == null) {
+            this.stream.end();
+          } else {
+            this.stream.end(this.body);
+          }
+        }
+      }).catch((error) => {
+        // console.error(error);
+        this.stream.destroy(error);
+      });
+      return 0;
+    }
+
+    if (this.isStreaming) {
+      this.getPipeline();
+    } else {
+      if (!this.headersSent) this.sendHeaders();
+      if (this.body == null) {
+        this.stream.end();
+      } else {
+        this.stream.end(this.body);
+      }
+    }
+    return 0;
+  }
+
+  // Alias
+
+  /**
+   * @param {number} status
+   * @return {this}
+   */
+  code(status) {
+    this.status = status;
+    return this;
+  }
+
+  /**
+   * @param {number} status
+   * @throws {Error<ERR_HEADER_SENT>}
+   * @return {this}
+   */
+  setStatus(status) {
+    if (this.headersSent) throw new Error('ERR_HEADER_SENT');
+    this.status = status;
+    return this;
   }
 }

package/lib/HttpTransaction.js

@@ -0,0 +1,146 @@
+/** @typedef {import('./HttpRequest.js').default} HttpRequest */
+/** @typedef {import('./HttpResponse.js').default} HttpResponse */
+/** @typedef {import('stream').Stream} Stream */
+
+/** @typedef {import('../types/index.js').MediaType} MediaType */
+/** @typedef {import('../types/index.js').Middleware} Middleware */
+/** @typedef {import('stream').Writable} Writable */
+
+/** @typedef {Partial<MediaType> & {parse:(this:HttpRequest)=>any|PromiseLike<any>, test?:(this:HttpRequest, mediaType: MediaType)=>boolean}} ContentReaderRegistration */
+
+/**
+ * @typedef {Object} PathHistoryEntry
+ * @prop {string} base
+ * @prop {number[]} treeIndex
+ */
+
+/**
+ * @typedef {Object} PathState
+ * @prop {PathHistoryEntry[]} history
+ * @prop {string} currentPath
+ */
+
+/**
+ * @typedef {Object} HttpTransactionState
+ * @prop {number[]} treeIndex Middleware level
+ * @prop {PathState} path
+ */
+
+/**
+ * @template {Object<string,any>} T
+ * @typedef HttpTransactionOptions
+ * @prop {string} httpVersion
+ * @prop {HttpRequest} [request]
+ * @prop {HttpResponse} [response]
+ * @prop {import('net').Socket|import('tls').TLSSocket} socket
+ * @prop {boolean} [canPing]
+ * @prop {(function():Promise<any>)|(function():any)} [onPing]
+ * @prop {boolean|function():boolean} [canPushPath]
+ * @prop {(path:string) => Promise<any>} [onPushPath]
+ * @prop {function():boolean} [onHeadersSent]
+ * @prop {(flush:boolean, end:boolean) => boolean} [onSendHeaders]
+ * @prop {T} [locals]
+ * @prop {HttpTransactionState} [state]
+ * @prop {Error} [error]
+ */
+
+/**
+ * @template {Object<string,any>} [T=any]
+ */
+export default class HttpTransaction {
+  /** @type {boolean|(()=>boolean)} */
+  #canPing = false;
+
+  /** @type {function():Promise<any>} */
+  #onPing = null;
+
+  /** @type {(path:string) => Promise<any>} */
+  #onPushPath = null;
+
+  /** @type {Array<string>} */
+  #pushedPaths = [];
+
+  /** @type {boolean|(()=>boolean)} */
+  #canPushPath = false;
+
+  #isErrorHandlerState = false;
+
+  /** @param {HttpTransactionOptions<T>} options */
+  constructor(options) {
+    this.request = options.request;
+    this.response = options.response;
+
+    /** @type {T} */
+    this.locals = options.locals || /** @type {T} */ ({});
+    this.state = options.state || {
+      treeIndex: [],
+      path: null,
+    };
+
+    this.socket = options.socket;
+    this.httpVersion = options.httpVersion;
+
+    this.#canPing = options.canPing ?? false;
+    this.#onPing = options.onPing;
+
+    this.#onPushPath = options.onPushPath;
+    this.#canPushPath = options.canPushPath ?? false;
+
+    this.error = options.error;
+  }
+
+  setErrorHandlerState() {
+    this.#isErrorHandlerState = true;
+  }
+
+  isErrorHandlerState() {
+    return this.#isErrorHandlerState;
+  }
+
+  get canPing() {
+    if (!this.#canPing) return false;
+    if (this.#canPing === true) return true;
+    return this.#canPing();
+  }
+
+  /**
+   * @return {Promise<any>}
+   */
+  ping() {
+    if (!this.#canPing) {
+      return Promise.reject(new Error('NOT_SUPPORTED'));
+    }
+    if (!this.#onPing) {
+      return Promise.reject(new Error('NOT_IMPLEMENTED'));
+    }
+    return this.#onPing();
+  }
+
+  get pushedPaths() {
+    return this.#pushedPaths;
+  }
+
+  get canPushPath() {
+    if (!this.#canPushPath) return false;
+    if (this.#canPushPath === true) return true;
+    return this.#canPushPath();
+  }
+
+  /**
+   * @param {string} [path]
+   * @return {Promise<any>}
+   */
+  async pushPath(path) {
+    if (this.#pushedPaths.includes(path)) {
+      throw new Error('ALREADY_PUSHED');
+    }
+    if (!this.#canPushPath) {
+      throw new Error('NOT_SUPPORTED');
+    }
+    if (!this.#onPushPath) {
+      throw new Error('NOT_IMPLEMENTED');
+    }
+    await this.#onPushPath(path);
+    this.#pushedPaths.push(path);
+  }
+}

package/middleware/AutoHeadersMiddleware.js

@@ -0,0 +1,73 @@
+/** @typedef {import('../lib/HttpResponse.js').default} HttpResponse */
+/** @typedef {import('../types').ResponseFinalizer} ResponseFinalizer */
+/** @typedef {import('../types').MiddlewareFunction} MiddlewareFunction */
+
+import { Transform } from 'node:stream';
+
+/**
+ * @typedef {Object} AutoHeadersMiddlewareOptions
+ * @prop {boolean} [setStatus=true]
+ * Automatically set `200` or `204` status if not set
+ */
+
+export default class AutoHeadersMiddleware {
+  /** @param {AutoHeadersMiddlewareOptions} options */
+  constructor(options = {}) {
+    this.setStatus = options.setStatus !== false;
+    this.finalizeResponse = this.finalizeResponse.bind(this);
+  }
+
+  /**
+   * @param {HttpResponse} response
+   * @return {void}
+   */
+  addTransformStream(response) {
+    let firstChunk = false;
+    response.pipes.push(new Transform({
+      transform: (chunk, encoding, callback) => {
+        if (!firstChunk) {
+          firstChunk = true;
+          if (!response.headersSent) {
+            if (response.statusCode == null) {
+              if (!this.setStatus) {
+                callback(new Error('NO_STATUS'));
+                return;
+              }
+              response.status = 200;
+            }
+            response.sendHeaders(false);
+          }
+        }
+        callback(null, chunk);
+      },
+      final: (callback) => {
+        if (!response.headersSent) {
+          if (this.setStatus && response.statusCode == null) {
+            response.status = 204;
+          }
+          response.sendHeaders(false);
+        }
+        callback();
+      },
+    }));
+  }
+
+  /** @type {ResponseFinalizer} */
+  finalizeResponse(response) {
+    if (response.headersSent) return;
+    if (response.isStreaming) {
+      this.addTransformStream(response);
+      return;
+    }
+
+    if (response.status == null && this.setStatus && Buffer.isBuffer(response.body)) {
+      response.status = response.body.byteLength ? 200 : 204;
+    }
+    response.sendHeaders();
+  }
+
+  /** @type {MiddlewareFunction} */
+  execute({ response }) {
+    response.finalizers.push(this.finalizeResponse);
+  }
+}