@adonisjs/session 7.0.0-0 → 7.0.0-10

package/build/src/session.js

@@ -6,368 +6,379 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { Exception } from '@poppinss/utils';
 import lodash from '@poppinss/utils/lodash';
 import { cuid } from '@adonisjs/core/helpers';
-import { Store } from './store.js';
+import { ReadOnlyStore, Store } from './store.js';
+import * as errors from './errors.js';
+import debug from './debug.js';
 /**
- * Session class exposes the API to read/write values to the session for
- * a given request.
+ * The session class exposes the API to read and write values to
+ * the session store.
+ *
+ * A session instance is isolated between requests but
+ * uses a centralized persistence store and
  */
 export class Session {
-    /**
-     * Session id for the current request. It will be different
-     * from the "this.sessionId" when regenerate is called.
-     */
-    #currentSessionId;
-    /**
-     * A instance of store with values read from the driver. The store
-     * in initiated inside the [[initiate]] method
-     */
-    #store;
-    /**
-     * Whether or not to re-generate the session id before committing
-     * session values.
-     */
-    #regeneratedSessionId = false;
-    /**
-     * Session key for setting flash messages
-     */
-    #flashMessagesKey = '__flash__';
-    /**
-     * The HTTP context for the current request.
-     */
-    #ctx;
-    /**
-     * Configuration for the session
-     */
     #config;
-    /**
-     * The session driver instance used to read and write session data.
-     */
     #driver;
+    #emitter;
+    #ctx;
+    #readonly = false;
+    #store;
     /**
-     * Set to true inside the `initiate` method
-     */
-    initiated = false;
-    /**
-     * A boolean to know if it's a fresh session or not. Fresh
-     * sessions are those, whose session id is not present
-     * in cookie
+     * Session id refers to the session id that will be committed
+     * as a cookie during the response.
      */
-    fresh = false;
+    #sessionId;
     /**
-     * A boolean to know if store is initiated in readonly mode
-     * or not. This is done during Websocket requests
+     * Session id from cookie refers to the value we read from the
+     * cookie during the HTTP request.
+     *
+     * This only might not exist during the first request. Also during
+     * session id re-generation, this value will be different from
+     * the session id.
      */
-    readonly = false;
+    #sessionIdFromCookie;
     /**
-     * Session id for the given request. A new session id is only
-     * generated when the cookie for the session id is missing
+     * Store of flash messages that be written during the
+     * HTTP request
      */
-    sessionId;
+    responseFlashMessages = new Store({});
     /**
-     * A copy of previously set flash messages
+     * Store of flash messages for the current HTTP request.
      */
     flashMessages = new Store({});
     /**
-     * A copy of flash messages. The `input` messages
-     * are overwritten when any of the input related
-     * methods are used.
-     *
-     * The `others` object is expanded with each call.
+     * The key to use for storing flash messages inside
+     * the session store.
      */
-    responseFlashMessages = new Store({});
-    constructor(ctx, config, driver) {
-        this.#ctx = ctx;
-        this.#config = config;
-        this.#driver = driver;
-        this.sessionId = this.#getSessionId();
-        this.#currentSessionId = this.sessionId;
-    }
+    flashKey = '__flash__';
     /**
-     * Returns a merged copy of flash messages or null
-     * when nothing is set
+     * Session id for the current HTTP request
      */
-    #setFlashMessages() {
-        if (this.responseFlashMessages.isEmpty) {
-            return;
-        }
-        const { input, ...others } = this.responseFlashMessages.all();
-        this.put(this.#flashMessagesKey, { ...input, ...others });
+    get sessionId() {
+        return this.#sessionId;
     }
     /**
-     * Returns the existing session id or creates one.
+     * A boolean to know if a fresh session is created during
+     * the request
      */
-    #getSessionId() {
-        const sessionId = this.#ctx.request.cookie(this.#config.cookieName);
-        if (sessionId) {
-            return sessionId;
-        }
-        this.fresh = true;
-        return cuid();
+    get fresh() {
+        return this.#sessionIdFromCookie === undefined;
     }
     /**
-     * Ensures the session store is initialized
+     * A boolean to know if session is in readonly
+     * state
      */
-    #ensureIsReady() {
-        if (!this.initiated) {
-            throw new Exception('Session store is not initiated yet. Make sure you are using the session hook', { code: 'E_RUNTIME_EXCEPTION', status: 500 });
-        }
+    get readonly() {
+        return this.#readonly;
     }
     /**
-     * Raises exception when session store is in readonly mode
+     * A boolean to know if session store has been initiated
      */
-    #ensureIsMutable() {
-        if (this.readonly) {
-            throw new Exception('Session store is in readonly mode and cannot be mutated', {
-                status: 500,
-                code: 'E_RUNTIME_EXCEPTION',
-            });
-        }
+    get initiated() {
+        return !!this.#store;
     }
     /**
-     * Touches the session cookie
+     * A boolean to know if the session id has been re-generated
+     * during the current request
      */
-    #touchSessionCookie() {
-        this.#ctx.logger.trace('touching session cookie');
-        this.#ctx.response.cookie(this.#config.cookieName, this.sessionId, this.#config.cookie);
+    get hasRegeneratedSession() {
+        return !!(this.#sessionIdFromCookie && this.#sessionIdFromCookie !== this.#sessionId);
     }
     /**
-     * Commits the session value to the store
+     * A boolean to know if the session store is empty
      */
-    async #commitValuesToStore() {
-        this.#ctx.logger.trace('persist session store with driver');
-        await this.#driver.write(this.sessionId, this.#store.toJSON());
+    get isEmpty() {
+        return this.#store?.isEmpty ?? true;
     }
     /**
-     * Touches the driver to make sure the session values doesn't expire
+     * A boolean to know if the session store has been
+     * modified
      */
-    async #touchDriver() {
-        this.#ctx.logger.trace('touch driver for liveliness');
-        await this.#driver.touch(this.sessionId);
+    get hasBeenModified() {
+        return this.#store?.hasBeenModified ?? false;
+    }
+    constructor(config, driver, emitter, ctx) {
+        this.#ctx = ctx;
+        this.#config = config;
+        this.#driver = driver;
+        this.#emitter = emitter;
+        this.#sessionIdFromCookie = ctx.request.cookie(config.cookieName, undefined);
+        this.#sessionId = this.#sessionIdFromCookie || cuid();
     }
     /**
-     * Reading flash messages from the last HTTP request and
-     * updating the flash messages bag
+     * Returns the flash messages store for a given
+     * mode
      */
-    #readLastRequestFlashMessage() {
-        if (this.readonly) {
-            return;
+    #getFlashStore(mode) {
+        if (!this.#store) {
+            throw new errors.E_SESSION_NOT_READY();
         }
-        this.flashMessages.update(this.pull(this.#flashMessagesKey, null));
+        if (mode === 'write' && this.readonly) {
+            throw new errors.E_SESSION_NOT_MUTABLE();
+        }
+        return this.responseFlashMessages;
     }
     /**
-     * Share flash messages & read only session's functions with views
-     * (only when view property exists)
+     * Returns the store instance for a given mode
      */
-    #shareLocalsWithView() {
-        // @ts-ignore may need to expose ./types/extended from adonisjs/view
-        if (!this.#ctx['view'] || typeof this.#ctx['view'].share !== 'function') {
-            return;
+    #getStore(mode) {
+        if (!this.#store) {
+            throw new errors.E_SESSION_NOT_READY();
+        }
+        if (mode === 'write' && this.readonly) {
+            throw new errors.E_SESSION_NOT_MUTABLE();
         }
-        // @ts-ignore may need to expose ./types/extended from adonisjs/view
-        this.#ctx['view'].share({
-            flashMessages: this.flashMessages,
-            session: {
-                get: this.get.bind(this),
-                has: this.has.bind(this),
-                all: this.all.bind(this),
-            },
-        });
+        return this.#store;
     }
     /**
-     * Initiating the session by reading it's value from the
-     * driver and feeding it to a store.
-     *
-     * Multiple calls to `initiate` results in a noop.
+     * Initiates the session store. The method results in a noop
+     * when called multiple times
      */
     async initiate(readonly) {
-        if (this.initiated) {
+        if (this.#store) {
             return;
         }
-        this.readonly = readonly;
-        const contents = await this.#driver.read(this.sessionId);
+        debug('initiating session (readonly: %s)', readonly);
+        this.#readonly = readonly;
+        const contents = await this.#driver.read(this.#sessionId);
         this.#store = new Store(contents);
-        this.initiated = true;
-        this.#readLastRequestFlashMessage();
-        this.#shareLocalsWithView();
-    }
-    /**
-     * Re-generates the session id. This can is used to avoid
-     * session fixation attacks.
-     */
-    regenerate() {
-        this.#ctx.logger.trace('explicitly re-generating session id');
-        this.sessionId = cuid();
-        this.#regeneratedSessionId = true;
+        /**
+         * Extract flash messages from the store and keep a local
+         * copy of it.
+         */
+        if (this.has(this.flashKey)) {
+            debug('reading flash data');
+            if (this.#readonly) {
+                this.flashMessages.update(this.get(this.flashKey, null));
+            }
+            else {
+                this.flashMessages.update(this.pull(this.flashKey, null));
+            }
+        }
+        /**
+         * Share session with the templates. We assume the view property
+         * is a reference to edge templates
+         */
+        if ('view' in this.#ctx) {
+            this.#ctx.view.share({
+                session: new ReadOnlyStore(this.#store.all()),
+                flashMessages: new ReadOnlyStore(this.flashMessages.all()),
+                old: function (key, defaultValue) {
+                    return this.flashMessages.get(key, defaultValue);
+                },
+            });
+        }
+        this.#emitter.emit('session:initiated', { session: this });
     }
     /**
-     * Set/update session value
+     * Put a key-value pair to the session data store
      */
     put(key, value) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.#store.set(key, value);
+        this.#getStore('write').set(key, value);
     }
     /**
-     * Find if the value exists in the session
+     * Check if a key exists inside the datastore
      */
     has(key) {
-        this.#ensureIsReady();
-        return this.#store.has(key);
+        return this.#getStore('read').has(key);
     }
     /**
-     * Get value from the session. The default value is returned
-     * when actual value is `undefined`
+     * Get the value of a key from the session datastore.
+     * You can specify a default value to use, when key
+     * does not exists or has undefined value.
      */
     get(key, defaultValue) {
-        this.#ensureIsReady();
-        return this.#store.get(key, defaultValue);
+        return this.#getStore('read').get(key, defaultValue);
     }
     /**
-     * Returns everything from the session
+     * Get everything from the session store
      */
     all() {
-        this.#ensureIsReady();
-        return this.#store.all();
+        return this.#getStore('read').all();
     }
     /**
-     * Remove value for a given key from the session
+     * Remove a key from the session datastore
      */
     forget(key) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.#store.unset(key);
+        return this.#getStore('write').unset(key);
     }
     /**
-     * The method is equivalent to calling `session.get` followed
-     * by `session.forget`
+     * Read value for a key from the session datastore
+     * and remove it simultaneously.
      */
     pull(key, defaultValue) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        return this.#store.pull(key, defaultValue);
+        return this.#getStore('write').pull(key, defaultValue);
     }
     /**
-     * Increment value for a number inside the session store. The
-     * method raises an error when underlying value is not
-     * a number
+     * Increment the value of a key inside the session
+     * store.
+     *
+     * A new key will be defined if does not exists already.
+     * The value of a new key will be 1
      */
     increment(key, steps = 1) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.#store.increment(key, steps);
+        return this.#getStore('write').increment(key, steps);
     }
     /**
-     * Decrement value for a number inside the session store. The
-     * method raises an error when underlying value is not
-     * a number
+     * Increment the value of a key inside the session
+     * store.
+     *
+     * A new key will be defined if does not exists already.
+     * The value of a new key will be -1
      */
     decrement(key, steps = 1) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.#store.decrement(key, steps);
+        return this.#getStore('write').decrement(key, steps);
     }
     /**
-     * Remove everything from the session
+     * Empty the session store
      */
     clear() {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.#store.clear();
+        return this.#getStore('write').clear();
     }
     /**
-     * Add a new flash message
+     * Flash validation error messages. Make sure the error
+     * is an instance of VineJS ValidationException
      */
+    flashValidationErrors(error) {
+        const errorsBag = error.messages.reduce((result, message) => {
+            if (result[message.field]) {
+                result[message.field].push(message.message);
+            }
+            else {
+                result[message.field] = [message.message];
+            }
+            return result;
+        }, {});
+        this.flashExcept(['_csrf', '_method']);
+        this.flash('errors', errorsBag);
+    }
     flash(key, value) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        /**
-         * Update value
-         */
         if (typeof key === 'string') {
             if (value) {
-                this.responseFlashMessages.set(key, value);
+                this.#getFlashStore('write').set(key, value);
             }
         }
         else {
-            this.responseFlashMessages.merge(key);
+            this.#getFlashStore('write').merge(key);
         }
     }
     /**
-     * Flash all form values
+     * Flash form input data to the flash messages store
      */
     flashAll() {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.responseFlashMessages.set('input', this.#ctx.request.original());
+        return this.#getFlashStore('write').set('input', this.#ctx.request.original());
     }
     /**
-     * Flash all form values except mentioned keys
+     * Flash form input data (except some keys) to the flash messages store
      */
     flashExcept(keys) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.responseFlashMessages.set('input', lodash.omit(this.#ctx.request.original(), keys));
+        this.#getFlashStore('write').set('input', lodash.omit(this.#ctx.request.original(), keys));
     }
     /**
-     * Flash only defined keys from the form values
+     * Flash form input data (only some keys) to the flash messages store
      */
     flashOnly(keys) {
-        this.#ensureIsReady();
-        this.#ensureIsMutable();
-        this.responseFlashMessages.set('input', lodash.pick(this.#ctx.request.original(), keys));
+        this.#getFlashStore('write').set('input', lodash.pick(this.#ctx.request.original(), keys));
     }
     /**
-     * Reflash existing flash messages
+     * Reflash messages from the last request in the current response
      */
     reflash() {
-        this.flash(this.flashMessages.all());
+        this.#getFlashStore('write').set('reflashed', this.flashMessages.all());
     }
     /**
-     * Reflash selected keys from the existing flash messages
+     * Reflash messages (only some keys) from the last
+     * request in the current response
      */
     reflashOnly(keys) {
-        this.flash(lodash.pick(this.flashMessages.all(), keys));
+        this.#getFlashStore('write').set('reflashed', lodash.pick(this.flashMessages.all(), keys));
     }
     /**
-     * Omit selected keys from the existing flash messages
-     * and flash the rest of values
+     * Reflash messages (except some keys) from the last
+     * request in the current response
      */
     reflashExcept(keys) {
-        this.flash(lodash.omit(this.flashMessages.all(), keys));
+        this.#getFlashStore('write').set('reflashed', lodash.omit(this.flashMessages.all(), keys));
+    }
+    /**
+     * Re-generate the session id and migrate data to it.
+     */
+    regenerate() {
+        this.#sessionId = cuid();
     }
     /**
-     * Writes value to the underlying session driver.
+     * Commit session changes. No more mutations will be
+     * allowed after commit.
      */
     async commit() {
-        if (!this.initiated) {
-            this.#touchSessionCookie();
-            await this.#touchDriver();
+        if (!this.#store || this.readonly) {
             return;
         }
         /**
-         * Cleanup old session and re-generate new session
+         * If the flash messages store is not empty, we should put
+         * its messages inside main session store.
+         */
+        if (!this.responseFlashMessages.isEmpty) {
+            const { input, reflashed, ...others } = this.responseFlashMessages.all();
+            this.put(this.flashKey, { ...reflashed, ...input, ...others });
+        }
+        debug('committing session data');
+        /**
+         * Touch the session id cookie to stay alive
+         */
+        this.#ctx.response.cookie(this.#config.cookieName, this.#sessionId, this.#config.cookie);
+        /**
+         * Delete the session data when the session store
+         * is empty.
+         *
+         * Also we only destroy the session id we read from the cookie.
+         * If there was no session id in the cookie, there won't be
+         * any data inside the store either.
          */
-        if (this.#regeneratedSessionId) {
-            await this.#driver.destroy(this.#currentSessionId);
+        if (this.isEmpty) {
+            if (this.#sessionIdFromCookie) {
+                await this.#driver.destroy(this.#sessionIdFromCookie);
+            }
+            this.#emitter.emit('session:committed', { session: this });
+            return;
         }
         /**
-         * Touch the session cookie to keep it alive.
+         * Touch the store expiry when the session store was
+         * not modified.
          */
-        this.#touchSessionCookie();
-        this.#setFlashMessages();
+        if (!this.hasBeenModified) {
+            if (this.#sessionIdFromCookie && this.#sessionIdFromCookie !== this.#sessionId) {
+                await this.#driver.destroy(this.#sessionIdFromCookie);
+                await this.#driver.write(this.#sessionId, this.#store.toJSON());
+                this.#emitter.emit('session:migrated', {
+                    fromSessionId: this.#sessionIdFromCookie,
+                    toSessionId: this.sessionId,
+                    session: this,
+                });
+            }
+            else {
+                await this.#driver.touch(this.#sessionId);
+            }
+            this.#emitter.emit('session:committed', { session: this });
+            return;
+        }
         /**
-         * Commit values to the store if not empty.
-         * Otherwise delete the session store to cleanup
-         * the storage space.
+         * Otherwise commit to the session store
          */
-        if (!this.#store.isEmpty) {
-            await this.#commitValuesToStore();
+        if (this.#sessionIdFromCookie && this.#sessionIdFromCookie !== this.#sessionId) {
+            await this.#driver.destroy(this.#sessionIdFromCookie);
+            await this.#driver.write(this.#sessionId, this.#store.toJSON());
+            this.#emitter.emit('session:migrated', {
+                fromSessionId: this.#sessionIdFromCookie,
+                toSessionId: this.sessionId,
+                session: this,
+            });
         }
         else {
-            await this.#driver.destroy(this.sessionId);
+            await this.#driver.write(this.#sessionId, this.#store.toJSON());
         }
+        this.#emitter.emit('session:committed', { session: this });
     }
 }

package/build/src/session_middleware.d.ts

@@ -1,5 +1,22 @@
-import type { HttpContext } from '@adonisjs/core/http';
+import { EmitterService } from '@adonisjs/core/types';
 import type { NextFn } from '@adonisjs/core/types/http';
+import { HttpContext } from '@adonisjs/core/http';
+import { Session } from './session.js';
+import type { SessionConfig } from './types/main.js';
+/**
+ * HttpContext augmentations
+ */
+declare module '@adonisjs/http-server' {
+    interface HttpContext {
+        session: Session;
+    }
+}
+/**
+ * Session middleware is used to initiate the session store
+ * and commit its values during an HTTP request
+ */
 export default class SessionMiddleware {
-    handle(ctx: HttpContext, next: NextFn): Promise<void>;
+    #private;
+    constructor(config: SessionConfig, emitter: EmitterService);
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
 }