Refactor SessionHost to be stricter on out-of-context calls

This distinguishes out-of-context calls as dev errors rather than hiding as user problems.
This also stops creating ephemeral `BehaviorSubject`s,
which could be a source of logic being lost & swallowed.

Author: CarsonF

src/common/session.ts

@@ -45,7 +45,7 @@ export class SessionPipe implements PipeTransform {
   constructor(private readonly sessionHost: SessionHost) {}
 
   transform() {
-    return this.sessionHost.current$.value;
+    return this.sessionHost.currentMaybe;
   }
 }
 

src/components/authentication/session.host.ts

@@ -2,12 +2,20 @@ import { Injectable, type OnModuleDestroy } from '@nestjs/common';
 import { AsyncLocalStorage } from 'async_hooks';
 import { BehaviorSubject } from 'rxjs';
 import { type Session } from '~/common';
+import { AsyncLocalStorageNoContextException } from '~/core/async-local-storage-no-context.exception';
 import { NoSessionException } from './no-session.exception';
 
 /**
  * A service holding the current session / user
  */
 export abstract class SessionHost {
+  /**
+   * Retrieve the current session.
+   *
+   * If this call is not within a {@link withSession} stack, a server error is thrown.
+   *
+   * If there is no current session, a {@link NoSessionException} is thrown.
+   */
   get current() {
     const value = this.current$.value;
     if (value) {
@@ -16,8 +24,34 @@ export abstract class SessionHost {
     throw new NoSessionException();
   }
 
+  /**
+   * Retrieve the current session or undefined.
+   *
+   * If this call is not within a {@link withSession} stack, a server error is thrown.
+   */
+  get currentMaybe() {
+    return this.current$.value;
+  }
+
+  /**
+   * Retrieve the current session subject.
+   *
+   * It must exist, meaning that this call is within a {@link withSession} stack.
+   * This subject could still not (yet) have an actual session value.
+   */
   abstract get current$(): BehaviorSubject<Session | undefined>;
 
+  /**
+   * Retrieve the current session or undefined.
+   *
+   * This is allowed to be called outside a {@link withSession} stack
+   * and will just return undefined.
+   */
+  abstract get currentIfInCtx(): Session | undefined;
+
+  /**
+   * Run a function with a given session.
+   */
   abstract withSession<R>(
     session: BehaviorSubject<Session | undefined> | Session | undefined,
     fn: () => R,
@@ -30,10 +64,18 @@ export class SessionHostImpl extends SessionHost implements OnModuleDestroy {
     BehaviorSubject<Session | undefined>
   >();
 
+  get currentIfInCtx() {
+    return this.als.getStore()?.value;
+  }
+
   get current$() {
-    return (
-      this.als.getStore() ?? new BehaviorSubject<Session | undefined>(undefined)
-    );
+    const subject = this.als.getStore();
+    if (!subject) {
+      throw new AsyncLocalStorageNoContextException(
+        'A session context has not been declared',
+      );
+    }
+    return subject;
   }
 
   withSession<R>(

src/core/data-loader/data-loader.config.ts

@@ -27,7 +27,7 @@ export class DataLoaderConfig {
         // If we have a session, use that as the cache key.
         // It will always be created / scoped within the GQL operation.
         // This ensures the cached data isn't shared between users.
-        const session = this.sessionHost.current$.value;
+        const session = this.sessionHost.currentMaybe;
         if (session) return session;
 
         return lifetimeIdFromExecutionContext(context);

src/core/database/database.service.ts

@@ -124,7 +124,7 @@ export class DatabaseService {
     parameters?: Record<string, any>,
   ): Query<Result> {
     const q = this.db.query() as Query<Result>;
-    q.params.addParam(this.sessionHost.current$.value?.userId, 'currentUser');
+    q.params.addParam(this.sessionHost.currentIfInCtx?.userId, 'currentUser');
     if (query) {
       q.raw(query, parameters);
     }

src/core/gel/gel.service.ts

@@ -115,7 +115,7 @@ export class Gel {
     const queryNames = getCurrentQueryNames();
     const traceName = queryNames?.xray ?? 'Query';
 
-    let currentActorId = this.sessionHost.current$.value?.userId;
+    let currentActorId = this.sessionHost.currentIfInCtx?.userId;
     // TODO temporarily check if UUID before applying global.
     // Once migration is complete this can be removed.
     currentActorId = isUUID(currentActorId) ? currentActorId : undefined;

src/core/graphql/graphql-tracing.plugin.ts

@@ -47,7 +47,7 @@ export class GraphqlTracingPlugin {
 
     return {
       onExecuteDone: () => {
-        const userId = this.sessionHost.current$.value?.userId;
+        const userId = this.sessionHost.currentMaybe?.userId;
         if (userId) {
           segment.setUser?.(userId);
         }