zibri 2.3.0 → 2.4.0

package/src/change-sets/change-set-repository.ts

@@ -1,5 +1,4 @@
-import { setTimeout } from 'node:timers/promises';
-import { isDeepStrictEqual } from 'util';
+import { isDeepStrictEqual } from 'node:util';
 
 import { Repository as TORepository } from 'typeorm';
 
@@ -7,7 +6,13 @@ import { AuthServiceInterface } from '../auth/auth-service.interface';
 import { ChangeSetEntity } from './models/change-set-entity.model';
 import { ChangeSetType } from './models/change-set-type.enum';
 import { ChangeSet, CreateChangeSetData } from './models/change-set.model';
+import { NewChange } from './models/change.model';
 import { BaseUser } from '../auth/models/base-user.model';
+import { HttpRequestContext } from '../context/request/http-request.context';
+import { WebsocketRequestContext } from '../context/request/websocket-request.context';
+import { DataSourceInterface } from '../data-source/data-sources/data-source.interface';
+import { BeforeReturnHook } from '../data-source/hooks/before-return';
+import { BeforeSaveHook } from '../data-source/hooks/before-save';
 import { BaseRepositoryOptions } from '../data-source/models/options/base-repository-options.model';
 import { CreateAllOptions } from '../data-source/models/options/create-all-options.model';
 import { CreateOptions } from '../data-source/models/options/create-options.model';
@@ -20,14 +25,16 @@ import { ZIBRI_DI_TOKENS } from '../di/default/zibri-di-tokens.default';
 import { inject } from '../di/inject.function';
 import { PropertyMetadata } from '../entity/decorators/property.decorator';
 import { BadRequestError } from '../error-handling/errors/bad-request.error';
-import { HttpRequest } from '../http/http-request.model';
+import { removeExcludeProperties } from '../global/model-registry/remove-exclude-properties.function';
+import { restoreExcludeProperties } from '../global/model-registry/restore-exclude-properties.function';
 import { LoggerInterface } from '../logging/logger.interface';
+import { DeepPartial } from '../types/deep-partial.type';
 import { Newable } from '../types/newable.type';
+import { JsonUtilities } from '../utilities/json.utilities';
 import { MetadataUtilities } from '../utilities/metadata.utilities';
+import { nowInNs } from '../utilities/now-in-ns.function';
 import { ObjectUtilities } from '../utilities/object.utilities';
 import { PromiseUtilities } from '../utilities/promise.utilities';
-import { NewChange } from './models/change.model';
-import { DeepPartial } from '../types/deep-partial.type';
 
 /**
  * The result for resetting a change set on an entity.
@@ -55,22 +62,29 @@ export class ChangeSetRepository<
     /**
      * Any keys that should be excluded from the change set.
      */
-    protected readonly keysToExcludeFromChangeSets: (keyof T)[];
+    protected readonly keysToExcludeFromChangeSets: Set<keyof T> = new Set();
 
     private readonly changeSetRepository: Repository<ChangeSet, CreateChangeSetData>;
     private readonly authService: AuthServiceInterface;
 
-    constructor(entityClass: Newable<T>, repo: TORepository<T> | Repository<T>, logger: LoggerInterface) {
-        super(entityClass, repo, logger);
+    constructor(
+        entityClass: Newable<T>,
+        repo: TORepository<T> | Repository<T>,
+        logger: LoggerInterface,
+        dataSource: DataSourceInterface,
+        beforeSave: BeforeSaveHook<T, CreateData, UpdateData>,
+        beforeReturn: BeforeReturnHook<T>
+    ) {
+        super(entityClass, repo, logger, dataSource, beforeSave, beforeReturn);
 
         this.authService = inject(ZIBRI_DI_TOKENS.AUTH_SERVICE);
         this.changeSetRepository = inject(repositoryTokenFor(ChangeSet));
 
-        this.keysToExcludeFromChangeSets = ['changeSets'];
+        this.keysToExcludeFromChangeSets.add('changeSets');
         const props: Record<string, PropertyMetadata> = MetadataUtilities.getModelProperties(entityClass);
         for (const [key, m] of ObjectUtilities.entries(props)) {
             if (m.excludeFromChangeSets) {
-                this.keysToExcludeFromChangeSets.push(key as keyof T);
+                this.keysToExcludeFromChangeSets.add(key as keyof T);
             }
         }
     }
@@ -191,7 +205,7 @@ export class ChangeSetRepository<
      * Rolls back all changes on the given entity that have happened since the given change set.
      * This DOES NOT preserve any changes that happened after the change set.
      * The given change set and any change sets after that will be deleted in the end.
-     * Calls rollbackByDate on the change set date internally.
+     * Calls rollbackToTimestamp on the change set timestamp internally.
      * @param entity - The entity to rollback.
      * @param changeSetId - The id of the changeSet to rollback to.
      * @param createChangeSet - Whether or not a change set should be created.
@@ -208,14 +222,14 @@ export class ChangeSetRepository<
         options?: BaseRepositoryOptions
     ): Promise<T> {
         const changeSet: ChangeSet = await this.changeSetRepository.findById(changeSetId, options);
-        return this.rollbackToDate(entity, changeSet.createdAt, createChangeSet, preserveCreateChangeSet, options);
+        return this.rollbackToTimestamp(entity, changeSet.createdAt, createChangeSet, preserveCreateChangeSet, options);
     }
 
     /**
      * Rolls back all changes on the entity with the given id that have happened since the given change set.
      * This DOES NOT preserve any changes that happened after the change set.
      * The given change set and any change sets after that will be deleted in the end.
-     * Calls rollbackByDate on the change set date internally.
+     * Calls rollbackToTimestampById on the change set timestamp internally.
      * @param id - The id of the entity to rollback.
      * @param changeSetId - The id of the changeSet to rollback to.
      * @param createChangeSet - Whether or not a change set should be created.
@@ -237,30 +251,30 @@ export class ChangeSetRepository<
                 'Could not rollback to the given change set: The changeSet doesn\'t belong to the entity with the given id.'
             );
         }
-        return this.rollbackToDateById(id, changeSet.createdAt, createChangeSet, preserveCreateChangeSet, options);
+        return this.rollbackToTimestampById(id, changeSet.createdAt, createChangeSet, preserveCreateChangeSet, options);
     }
 
     /**
-     * Rolls back all changes on the given entity that have happened since the given date.
-     * This DOES NOT preserve any changes that happened after the date.
-     * Any change sets after the given date will be deleted in the end.
+     * Rolls back all changes on the given entity that have happened since the given timestamp.
+     * This DOES NOT preserve any changes that happened after the timestamp.
+     * Any change sets after the given timestamp will be deleted in the end.
      * @param entity - The entity to rollback.
-     * @param date - The date to which the rollback should happen.
+     * @param timestampInNs - The timestamp to which the rollback should happen with nanosecond precision.
      * @param createChangeSet - Whether or not a change set should be created.
      * @param preserveCreateChangeSet - Whether or not create change sets should be preserved.
      * In that case the entity gets reset to the state after the create change set. Also, the create change set isn't deleted.
      * @param options - Additional options, eg. Transaction.
      * @returns The updated entity.
      */
-    async rollbackToDate(
+    async rollbackToTimestamp(
         entity: T,
-        date: Date,
+        timestampInNs: bigint,
         createChangeSet: boolean = true,
         preserveCreateChangeSet: boolean = true,
         options?: BaseRepositoryOptions
     ): Promise<T> {
         const changeSets: ChangeSet[] = await this.changeSetRepository.findAll({
-            where: { changeSetEntityId: entity.id, createdAt: { after: date } },
+            where: { changeSetEntityId: entity.id, createdAt: { greaterThan: timestampInNs } },
             relations: ['changes'],
             order: { createdAt: 'ASC' }
         });
@@ -282,33 +296,33 @@ export class ChangeSetRepository<
     }
 
     /**
-     * Rolls back all changes on the entity with the given id that have happened since the given date.
-     * This DOES NOT preserve any changes that happened after the date.
-     * Any change sets after the given date will be deleted in the end.
+     * Rolls back all changes on the entity with the given id that have happened since the given timestamp.
+     * This DOES NOT preserve any changes that happened after the timestamp.
+     * Any change sets after the given timestamp will be deleted in the end.
      * @param id - The id of the entity to rollback.
-     * @param date - The date to which the rollback should happen.
+     * @param timestampInNs - The timestamp to which the rollback should happen with nanosecond precision.
      * @param createChangeSet - Whether or not a change set should be created.
      * @param preserveCreateChangeSet - Whether or not create change sets should be preserved.
      * In that case the entity gets reset to the state after the create change set. Also, the create change set isn't deleted.
      * @param options - Additional options, eg. Transaction.
      * @returns The updated entity.
      */
-    async rollbackToDateById(
+    async rollbackToTimestampById(
         id: T['id'],
-        date: Date,
+        timestampInNs: bigint,
         createChangeSet: boolean = true,
         preserveCreateChangeSet: boolean = true,
         options?: BaseRepositoryOptions
     ): Promise<T> {
         const entity: T = await this.findById(id, options);
-        return this.rollbackToDate(entity, date, createChangeSet, preserveCreateChangeSet, options);
+        return this.rollbackToTimestamp(entity, timestampInNs, createChangeSet, preserveCreateChangeSet, options);
     }
 
     /**
-     * Rolls back all changes on the entities found with the given where filter to the state of the given date.
-     * This DOES NOT preserve any changes that happened after the date.
-     * Any change sets after the given date will be deleted in the end.
-     * @param date - The date to which the rollback should happen.
+     * Rolls back all changes on the entities found with the given where filter to the state of the given timestamp.
+     * This DOES NOT preserve any changes that happened after the timestamp.
+     * Any change sets after the given timestamp will be deleted in the end.
+     * @param timestampInNs - The timestamp to which the rollback should happen with nanosecond precision.
      * @param where - A filter to only rollback some entities.
      * @param createChangeSet - Whether or not a change set should be created.
      * @param preserveCreateChangeSet - Whether or not create change sets should be preserved.
@@ -316,8 +330,8 @@ export class ChangeSetRepository<
      * @param options - Additional options, eg. Transaction.
      * @returns The updated entity.
      */
-    async rollbackAllToDate(
-        date: Date,
+    async rollbackAllToTimestamp(
+        timestampInNs: bigint,
         where?: Where<T>,
         createChangeSet: boolean = true,
         preserveCreateChangeSet: boolean = true,
@@ -326,7 +340,7 @@ export class ChangeSetRepository<
         const entitiesToRollback: T[] = await this.findAll({ where: where, ...options });
         await PromiseUtilities.allChunked(
             entitiesToRollback,
-            e => this.rollbackToDate(e, date, createChangeSet, preserveCreateChangeSet, options)
+            e => this.rollbackToTimestamp(e, timestampInNs, createChangeSet, preserveCreateChangeSet, options)
         );
         return entitiesToRollback.length;
     }
@@ -347,17 +361,25 @@ export class ChangeSetRepository<
         options?: CreateOptions,
         force: boolean = false
     ): Promise<void> {
-        await setTimeout(1); // TODO: Better way to guarantee a different time stamp on change sets.
+        restoreExcludeProperties(entityPriorChanges, this.entityClass);
+        restoreExcludeProperties(data, this.entityClass);
+        const changes: NewChange[] = this.getChangesFromData(entityPriorChanges, data, type);
+        await Promise.all([
+            removeExcludeProperties(entityPriorChanges, this.entityClass),
+            removeExcludeProperties(data, this.entityClass)
+        ]);
+
+        if (!force && !changes.length) {
+            return;
+        }
+
         const changeSetData: CreateChangeSetData = {
             changeSetEntityId: entityPriorChanges.id,
             type: type,
-            createdAt: new Date(),
+            createdAt: nowInNs(),
             createdBy: await this.getCreatedBy(),
-            changes: this.getChangesFromData(entityPriorChanges, data, type)
+            changes
         };
-        if (!force && !changeSetData.changes.length) {
-            return;
-        }
         await this.changeSetRepository.create(changeSetData, options);
     }
 
@@ -378,13 +400,23 @@ export class ChangeSetRepository<
         force: boolean = false
     ): Promise<void> {
         const userId: string | undefined = await this.getCreatedBy();
-        await setTimeout(1); // TODO: Better way to guarantee a different time stamp on change sets.
-        let changeSetData: CreateChangeSetData[] = entitiesPriorChanges.map((e, i) => ({
-            changeSetEntityId: e.id,
-            type: type,
-            createdAt: new Date(),
-            createdByUserId: userId,
-            changes: this.getChangesFromData(e, data[i], type)
+
+        let changeSetData: CreateChangeSetData[] = await Promise.all(entitiesPriorChanges.map(async (e, i) => {
+            restoreExcludeProperties(e, this.entityClass);
+            restoreExcludeProperties(data[i], this.entityClass);
+            const changes: NewChange[] = this.getChangesFromData(e, data[i], type);
+            await Promise.all([
+                removeExcludeProperties(e, this.entityClass),
+                removeExcludeProperties(data[i], this.entityClass)
+            ]);
+
+            return {
+                changeSetEntityId: e.id,
+                type,
+                createdAt: nowInNs(),
+                createdByUserId: userId,
+                changes
+            };
         }));
         if (!force) {
             changeSetData = changeSetData.filter(d => d.changes.length);
@@ -423,12 +455,12 @@ export class ChangeSetRepository<
      * @returns The id of the currently logged in user or undefined if that didn't work.
      */
     protected async getCreatedBy(): Promise<string | undefined> {
-        const currentRequest: HttpRequest | undefined = inject(ZIBRI_DI_TOKENS.CURRENT_REQUEST);
-        if (!currentRequest) {
+        const context: HttpRequestContext | WebsocketRequestContext | undefined = inject(ZIBRI_DI_TOKENS.CURRENT_REQUEST_CONTEXT);
+        if (!context) {
             throw new Error('No request in context');
         }
         const user: BaseUser<string> | undefined = await this.authService.getCurrentUser(
-            currentRequest,
+            context,
             this.authService.strategies,
             false
         );
@@ -445,7 +477,7 @@ export class ChangeSetRepository<
     ): (keyof (CreateData | UpdateData | DeepPartial<T>))[] {
         const keys: (keyof (CreateData | UpdateData | DeepPartial<T>))[] = [];
         for (const key in data) {
-            if (!this.keysToExcludeFromChangeSets.includes(key as keyof T)) {
+            if (!this.keysToExcludeFromChangeSets.has(key as keyof T)) {
                 keys.push(key as keyof (CreateData | UpdateData | DeepPartial<T>));
             }
         }
@@ -465,7 +497,7 @@ export class ChangeSetRepository<
     ): boolean {
         return !(
             isDeepStrictEqual(previousValue, newValue)
-            || JSON.stringify(previousValue) === JSON.stringify(newValue)
+            || JsonUtilities.stringify(previousValue) === JsonUtilities.stringify(newValue)
         );
     }
 }

package/src/change-sets/models/change-set.model.ts

@@ -18,10 +18,10 @@ export class ChangeSet extends BaseEntity {
     @Property.string({ enum: ChangeSetType })
     type!: ChangeSetType;
     /**
-     * The time at which the change happened.
+     * The time at which the change happened with nanosecond precision.
      */
-    @Property.date()
-    createdAt!: Date;
+    @Property.number({ format: 'bigint' })
+    createdAt!: bigint;
     /**
      * The id of the user that changed something.
      */

package/src/change-sets/models/change.model.ts

@@ -27,7 +27,7 @@ export class Change<T = unknown> extends BaseEntity {
     /**
      * The change set that this change belongs to.
      */
-    @Property.manyToOne({ target: () => ChangeSet, inverseSide: 'changes', required: false })
+    @Property.manyToOne({ target: () => ChangeSet, inverseSide: 'changes' })
     changeSet!: ChangeSet;
 }
 

package/src/change-sets/soft-delete-repository.ts

@@ -16,6 +16,9 @@ import { SoftDeleteFindOneOptions } from './models/soft-delete-find-one-options.
 import { SoftDeleteUpdateAllOptions } from './models/soft-delete-update-all-options.model';
 import { SoftDeleteUpdateByIdOptions } from './models/soft-delete-update-by-id-options.model';
 import { SoftDeleteWhere } from './models/soft-delete-where.model';
+import { DataSourceInterface } from '../data-source/data-sources/data-source.interface';
+import { BeforeReturnHook } from '../data-source/hooks/before-return';
+import { BeforeSaveHook } from '../data-source/hooks/before-save';
 import { Where } from '../data-source/models/where/where-filter.model';
 import { NotFoundError } from '../error-handling/errors/not-found.error';
 import { LoggerInterface } from '../logging/logger.interface';
@@ -51,10 +54,18 @@ export class SoftDeleteRepository<
 >
     extends ChangeSetRepository<T, CreateData, UpdateData> {
 
-    protected override readonly keysToExcludeFromChangeSets: (keyof T)[] = ['changeSets', 'deleted'];
-
-    constructor(entityClass: Newable<T>, repo: TORepository<T> | Repository<T>, logger: LoggerInterface) {
-        super(entityClass, repo, logger);
+    protected override readonly keysToExcludeFromChangeSets: Set<keyof T> = new Set();
+
+    constructor(
+        entityClass: Newable<T>,
+        repo: TORepository<T> | Repository<T>,
+        logger: LoggerInterface,
+        dataSource: DataSourceInterface,
+        beforeSave: BeforeSaveHook<T, CreateData, UpdateData>,
+        beforeReturn: BeforeReturnHook<T>
+    ) {
+        super(entityClass, repo, logger, dataSource, beforeSave, beforeReturn);
+        this.keysToExcludeFromChangeSets.add('deleted');
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
@@ -129,17 +140,17 @@ export class SoftDeleteRepository<
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc
-    async deleteById(id: T['id'], options?: SoftDeleteByIdOptions): Promise<void> {
+    async deleteById(id: T['id'], options?: SoftDeleteByIdOptions): Promise<T> {
         if (options?.hardDelete === true) {
-            await super.deleteById(id, options);
-            return;
+            return await super.deleteById(id, options);
         }
         const entity: T = await this.findById(id, options);
         if (entity.deleted) {
             throw new NotFoundError(`Could not find ${this.entityClass.name} with id "${id}".`);
         }
-        await this.updateById(id, { deleted: true } as UpdateData, options);
+        const res: T = await this.updateById(id, { deleted: true } as UpdateData, options);
         await this.createChangeSet(entity, { deleted: true } as UpdateData, ChangeSetType.DELETE, options, true);
+        return res;
     }
 
     // eslint-disable-next-line jsdoc/require-jsdoc

package/src/context/als.utilities.ts

@@ -0,0 +1,84 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { HttpRequestContext } from './request/http-request.context';
+import { WebsocketRequestContext } from './request/websocket-request.context';
+import { LogCacheContext } from '../logging/log-context.model';
+
+/**
+ * Encapsulates functionality around async local storage.
+ */
+export abstract class AlsUtilities {
+    private static readonly httpRequest: AsyncLocalStorage<HttpRequestContext> = new AsyncLocalStorage<HttpRequestContext>();
+    private static readonly websocketRequest: AsyncLocalStorage<WebsocketRequestContext> = new AsyncLocalStorage<WebsocketRequestContext>();
+    private static readonly cacheContext: AsyncLocalStorage<LogCacheContext[]> = new AsyncLocalStorage<LogCacheContext[]>();
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    static getCurrentRequestContext(): HttpRequestContext | WebsocketRequestContext | undefined {
+        return this.getCurrentHttpRequestContext() ?? this.getCurrentWebsocketRequestContext();
+    }
+
+    /**
+     * Runs the given function with the request context saved in async local storage.
+     * @param context - The request context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithHttpRequestContext<T>(context: HttpRequestContext, fn: () => T): T {
+        return this.httpRequest.run(context, fn);
+    }
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active http request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    protected static getCurrentHttpRequestContext(): HttpRequestContext | undefined {
+        const store: HttpRequestContext | undefined = this.httpRequest.getStore();
+        return store;
+    }
+
+    /**
+     * Runs the given function with the request context saved in async local storage.
+     * @param context - The request context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithWebsocketRequestContext<T>(context: WebsocketRequestContext, fn: () => T): T {
+        return this.websocketRequest.run(context, fn);
+    }
+
+    /**
+     * Resolves the currently active request context from the async local storage.
+     * @returns The currently active websocket request context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    protected static getCurrentWebsocketRequestContext(): WebsocketRequestContext | undefined {
+        const store: WebsocketRequestContext | undefined = this.websocketRequest.getStore();
+        return store;
+    }
+
+    /**
+     * Runs the given function with the cache context saved in async local storage.
+     * @param context - The cache context.
+     * @param fn - The function to run.
+     * @returns The result of the function.
+     */
+    static runWithCacheContext<T>(context: LogCacheContext, fn: () => T): T {
+        const existing: LogCacheContext[] = this.getCurrentCacheContext() ?? [];
+        // New array — doesn't mutate the parent scope's array
+        return this.cacheContext.run([...existing, context], fn);
+    }
+
+    /**
+     * Resolves the currently active cache context from the async local storage.
+     * @returns The currently active cache context.
+     * @throws When the async local storage store has not been initialized yet.
+     */
+    static getCurrentCacheContext(): LogCacheContext[] | undefined {
+        return this.cacheContext.getStore();
+    }
+}

package/src/context/base-context.ts

@@ -0,0 +1,12 @@
+/**
+ * The base context that any context needs to extend from.
+ */
+export abstract class BaseContext<T> {
+    abstract readonly type: T;
+    /**
+     * The cached token values.
+     */
+    protected readonly tokenValues: Map<string, unknown> = new Map();
+
+    constructor() {}
+}

package/src/context/request/http-request.context.test.ts

@@ -0,0 +1,93 @@
+
+import { afterAll, beforeAll, describe, expect, test } from '@jest/globals';
+
+import { RequestContextToken } from './request-context-token.model';
+import { createTestDataSource, defaultTestServerEntities } from '../../__testing__/test-server/create-test-data-source.function';
+import { StartedTestServer, startTestServer } from '../../__testing__/test-server/start-test-server.function';
+import { Repository } from '../../data-source/repository';
+import { InjectRepository } from '../../di/decorators/inject-repository.decorator';
+import { BaseEntity } from '../../entity/base-entity.model';
+import { Entity } from '../../entity/decorators/entity.decorator';
+import { Property } from '../../entity/decorators/property.decorator';
+import { KnownHeader } from '../../http/known-header.enum';
+import { Controller } from '../../routing/decorators/controller.decorator';
+import { Get } from '../../routing/decorators/get.decorator';
+
+const CURRENT_USER: RequestContextToken<{ isAdmin: boolean }> = new RequestContextToken(
+    'current-user',
+    (ctx) => {
+        const auth: string | undefined = ctx.request.headers[KnownHeader.AUTHORIZATION];
+        return { isAdmin: auth === 'admin' };
+    }
+);
+
+@Entity()
+class Test extends BaseEntity {
+    @Property.string({
+        exclude: async (_, ctx) => {
+            if (!ctx) {
+                return false;
+            }
+            const { isAdmin } = await ctx.get(CURRENT_USER);
+            return !isAdmin;
+        }
+    })
+    secret!: string;
+
+    @Property.string({
+        default: async (_, ctx) => {
+            if (!ctx) {
+                throw new Error('Could not find request context when resolving default value for Test.label');
+            }
+            const { isAdmin } = await ctx.get(CURRENT_USER);
+            return isAdmin ? 'admin-default' : 'user-default';
+        }
+    })
+    label!: string;
+}
+
+@Controller('/context-test')
+class ContextTestController {
+    constructor(
+        @InjectRepository(Test)
+        private readonly testRepository: Repository<Test>
+    ) {}
+
+    @Get('/')
+    async get(): Promise<Test> {
+        return await this.testRepository.create({ secret: 'top-secret' });
+    }
+}
+
+let server: StartedTestServer;
+let baseUrl: string;
+describe('request context integration', () => {
+    beforeAll(async () => {
+        server = await startTestServer({
+            dataSources: [createTestDataSource({ entities: [...defaultTestServerEntities, Test] })],
+            controllers: [ContextTestController]
+        });
+        baseUrl = await server.start();
+    }, 15000);
+
+    afterAll(async () => {
+        await server.shutdown();
+    });
+
+    test('context is available during exclude/default evaluation and is cached', async () => {
+        const res: Response = await fetch(`${baseUrl}/context-test`, { headers: { Authorization: 'admin' } });
+        expect(res.status).toBe(200);
+
+        const body: Test = await res.json() as Test;
+        expect(body.secret).toBe('top-secret');
+        expect(body.label).toBe('admin-default');
+    });
+
+    test('exclude sees the request context for non-admin users', async () => {
+        const res: Response = await fetch(`${baseUrl}/context-test`, { headers: { Authorization: 'user' } });
+
+        const body: Test = await res.json() as Test;
+        expect(body.secret).toBeUndefined();
+        expect(body.label).toBe('user-default');
+    });
+});

package/src/context/request/http-request.context.ts

@@ -0,0 +1,44 @@
+
+import { BaseContext } from '../base-context';
+import { RequestContextToken } from './request-context-token.model';
+import { HttpRequest } from '../../http/http-request.model';
+import { HttpResponse } from '../../http/http-response.model';
+import { Newable } from '../../types/newable.type';
+
+/**
+ * The context of an incoming http request.
+ */
+export class HttpRequestContext extends BaseContext<'http-request'> {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    readonly type: 'http-request' = 'http-request';
+
+    constructor(
+        readonly request: HttpRequest,
+        readonly response: HttpResponse,
+        readonly controllerClass: Newable<unknown> | undefined,
+        readonly controllerMethod: string | undefined
+    ) {
+        super();
+    }
+
+    /**
+     * Whether or not a value for the given token has been cached.
+     * @param token - The token to check.
+     * @returns True if a value has been cached, false otherwise.
+     */
+    has<T>(token: RequestContextToken<T>): boolean {
+        return this.tokenValues.has(token.key);
+    }
+
+    /**
+     * Either returns the cached value for the given token or initializes and caches a new value.
+     * @param token - The token to get the value of.
+     * @returns Either the cached or a new value.
+     */
+    get<T>(token: RequestContextToken<T>): T {
+        if (!this.has(token)) {
+            this.tokenValues.set(token.key, token.fn(this));
+        }
+        return this.tokenValues.get(token.key) as T;
+    }
+}