Start JSDocs

lib/src/http/kernel/Kernel.ts

@@ -6,6 +6,9 @@ import {Service} from '../../../../di/src/decorator/Service.ts'
 import {Request} from '../Request.ts'
 import {Logging} from '../../service/logging/Logging.ts'
 
+/**
+ * Interface for fluently registering kernel modules into the kernel.
+ */
 export interface ModuleRegistrationFluency {
     before: (other?: Instantiable<Module>) => Kernel,
     after: (other?: Instantiable<Module>) => Kernel,
@@ -14,18 +17,45 @@ export interface ModuleRegistrationFluency {
     core: () => Kernel,
 }
 
+/**
+ * Error thrown when a kernel module is requested that does not exist w/in the kernel.
+ * @extends Error
+ */
 export class KernelModuleNotFoundError extends Error {
     constructor(mod_name: string) {
         super(`The kernel module ${mod_name} is not registered with the kernel.`)
     }
 }
 
+/**
+ * A basic HTTP kernel used to process incoming and outgoing middleware.
+ * @extends AppClass
+ */
 @Service()
 export default class Kernel extends AppClass {
+    /**
+     * Collection of preflight modules to apply.
+     * @type Collection<Module>
+     */
     protected preflight: Collection<Module> = new Collection<Module>()
+
+    /**
+     * Module considered to be the main handler.
+     * @type Module
+     */
     protected inflight?: Module
+
+    /**
+     * Collection of postflight modules to apply.
+     * @type Collection<Module>
+     */
     protected postflight: Collection<Module> = new Collection<Module>()
 
+    /**
+     * Handle the incoming request, applying the preflight modules, inflight module, then postflight modules.
+     * @param {Request} request
+     * @return Promise<Request>
+     */
     public async handle(request: Request): Promise<Request> {
         const logger = this.make(Logging)
 
@@ -47,6 +77,11 @@ export default class Kernel extends AppClass {
         return request
     }
 
+    /**
+     * Get a fluent interface for registering the given kernel module.
+     * @param {Instantiable<Module>} module
+     * @return ModuleRegistrationFluency
+     */
     public register(module: Instantiable<Module>): ModuleRegistrationFluency {
         this.make(Logging).verbose(`Registering HTTP kernel module: ${module.name}`)
         return {

lib/src/http/kernel/Module.ts

@@ -2,15 +2,33 @@ import {Request} from '../Request.ts'
 import Kernel from './Kernel.ts'
 import AppClass from '../../lifecycle/AppClass.ts'
 
+/**
+ * Base class for HTTP kernel modules.
+ * @extends AppClass
+ */
 export default class Module extends AppClass {
+    /**
+     * Returns true if the given module should be applied to the incoming request.
+     * @param {Request} request
+     * @return Promise<boolean>
+     */
     public async match(request: Request): Promise<boolean> {
         return true
     }
 
+    /**
+     * Apply the module to the incoming request.
+     * @param {Request} request
+     * @return Promise<Request>
+     */
     public async apply(request: Request): Promise<Request> {
         return request
     }
 
+    /**
+     * Register this module with the given HTTP kernel.
+     * @param {Kernel} kernel
+     */
     public static register(kernel: Kernel) {
         kernel.register(this).before()
     }

lib/src/http/kernel/module/ApplyRouteHandlers.ts

@@ -7,6 +7,10 @@ import ResponseFactory from '../../response/ResponseFactory.ts'
 import {http, error} from '../../response/helpers.ts'
 import {HTTPStatus} from '../../../const/http.ts'
 
+/**
+ * HTTP kernel module to apply route handlers to the incoming request.
+ * @extends Module
+ */
 @Injectable()
 export default class ApplyRouteHandlers extends Module {
     public static register(kernel: Kernel) {
@@ -19,6 +23,11 @@ export default class ApplyRouteHandlers extends Module {
         super()
     }
 
+    /**
+     * Apply the route handler to the request.
+     * @param {Request} request
+     * @return Promise<Request>
+     */
     public async apply(request: Request): Promise<Request> {
         if ( !request.route ) { // Route not found
             const factory = http(HTTPStatus.NOT_FOUND)

lib/src/http/kernel/module/InjectSession.ts

@@ -6,6 +6,10 @@ import SessionManager from '../../session/SessionManager.ts'
 import {Logging} from '../../../service/logging/Logging.ts'
 import {Injectable} from '../../../../../di/src/decorator/Injection.ts'
 
+/**
+ * HTTP kernel module to retrieve and inject the session into the request.
+ * @extends Module
+ */
 @Injectable()
 export default class InjectSession extends Module {
     public static register(kernel: Kernel) {
@@ -19,6 +23,10 @@ export default class InjectSession extends Module {
         super()
     }
 
+    /**
+     * Lookup or create the session object and inject it into the request.
+     * @param {Request} request
+     */
     public async apply(request: Request): Promise<Request> {
         if ( request.session ) return request
 

lib/src/http/kernel/module/MountActivatedRoute.ts

@@ -8,6 +8,10 @@ import Config from '../../../unit/Config.ts'
 import ActivatedRoute from '../../routing/ActivatedRoute.ts'
 import {Injectable} from '../../../../../di/src/decorator/Injection.ts'
 
+/**
+ * HTTP kernel middleware to resolve and mount the registered route onto the request.
+ * @extends Module
+ */
 @Injectable()
 export default class MountActivatedRoute extends Module {
     public static register(kernel: Kernel) {
@@ -22,6 +26,10 @@ export default class MountActivatedRoute extends Module {
         super()
     }
 
+    /**
+     * Parse and resolve the route and mount it into the request object.
+     * @param {Request} request
+     */
     public async apply(request: Request): Promise<Request> {
         let incoming = this.routing.resolve([request.path])
         this.logger.info(`${request.method} ${incoming}`)

lib/src/http/kernel/module/PersistSession.ts

@@ -2,11 +2,19 @@ import Module from '../Module.ts'
 import Kernel from '../Kernel.ts'
 import {Request} from '../../Request.ts'
 
+/**
+ * Persist the session data before closing the request.
+ * @extends Module
+ */
 export default class PersistSession extends Module {
     public static register(kernel: Kernel) {
         kernel.register(this).last()
     }
 
+    /**
+     * Persist the session.
+     * @param {Request} request
+     */
     public async apply(request: Request): Promise<Request> {
         await request.session.persist()
         return request

lib/src/http/kernel/module/PrepareRequest.ts

@@ -2,12 +2,20 @@ import Module from '../Module.ts'
 import Kernel from '../Kernel.ts'
 import {Request} from '../../Request.ts'
 
+/**
+ * HTTP kernel module to call the request's prepare method.
+ * @extends Module
+ */
 export default class PrepareRequest extends Module {
 
     public static register(kernel: Kernel) {
         kernel.register(this).first()
     }
 
+    /**
+     * Prepare the request for Daton processing.
+     * @param {Request} request
+     */
     public async apply(request: Request): Promise<Request> {
         await request.prepare()
         return request

lib/src/http/kernel/module/SetDatonHeaders.ts

@@ -4,6 +4,10 @@ import {Request} from '../../Request.ts'
 import {Injectable} from '../../../../../di/src/decorator/Injection.ts'
 import Config from '../../../unit/Config.ts'
 
+/**
+ * Apply the default Daton headers to the outgoing response.
+ * @extends Module
+ */
 @Injectable()
 export default class SetDatonHeaders extends Module {
     public static register(kernel: Kernel) {
@@ -16,6 +20,10 @@ export default class SetDatonHeaders extends Module {
         super()
     }
 
+    /**
+     * Apply the outgoing response headers.
+     * @param request
+     */
     public async apply(request: Request): Promise<Request> {
         const text = this.config.get('server.powered_by.text', 'Daton')
         request.response.headers.set('X-Powered-By', text)

lib/src/http/kernel/module/SetSessionCookie.ts

@@ -6,6 +6,10 @@ import Utility from '../../../service/utility/Utility.ts'
 import {Injectable} from '../../../../../di/src/decorator/Injection.ts'
 import {Logging} from '../../../service/logging/Logging.ts'
 
+/**
+ * HTTP kernel module to set the Daton session cookie, if it doesn't exist.
+ * @extends Module
+ */
 @Injectable()
 export default class SetSessionCookie extends Module {
 
@@ -19,6 +23,10 @@ export default class SetSessionCookie extends Module {
         super()
     }
 
+    /**
+     * If one doesn't exist, generate and set the daton.session cookie.
+     * @param {Request} request
+     */
     public async apply(request: Request): Promise<Request> {
         if ( !(await request.cookies.has('daton.session')) ) {
             const cookie = `${this.utility.uuid()}-${this.utility.uuid()}`