From 7535444e87ba2a6d04cf088a9fb51e3543e5aa90 Mon Sep 17 00:00:00 2001 From: sideborg <86470679+sideborg@users.noreply.github.com> Date: Mon, 27 May 2024 09:15:42 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'content/2.nuxt?= =?UTF-8?q?-auth/'=20with=20remote=20'docs/content/'=20(#183)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: sideborg --- .../2.configuration/2.nuxt-config.md | 18 +++-- .../2.configuration/5.session-config.md | 73 +++++++++++++++++++ 2 files changed, 86 insertions(+), 5 deletions(-) create mode 100644 content/2.nuxt-auth/2.configuration/5.session-config.md diff --git a/content/2.nuxt-auth/2.configuration/2.nuxt-config.md b/content/2.nuxt-auth/2.configuration/2.nuxt-config.md index a618654b..9cbfc6f3 100644 --- a/content/2.nuxt-auth/2.configuration/2.nuxt-config.md +++ b/content/2.nuxt-auth/2.configuration/2.nuxt-config.md @@ -68,7 +68,7 @@ interface ModuleOptions { * Configuration of the application-side session. You can configure the following attributes: * - enableRefreshPeriodically: Whether to refresh the session every `X` milliseconds. Set this to `false` to turn it off. The session will only be refreshed if a session already exists. Setting this to `true` will refresh the session every second. Setting this to `false` will turn off session refresh. Setting this to a number `X` will refresh the session every `X` milliseconds. * - enableRefreshOnWindowFocus: Whether to refresh the session every time the browser window is refocused. - * + * * @example { enableRefreshPeriodically: 5000 } * @example { enableRefreshOnWindowFocus: false } * @default { enableRefreshPeriodically: false, enableRefreshOnWindowFocus: true } @@ -231,7 +231,7 @@ type ProviderLocal = { */ maxAgeInSeconds?: number, /** - * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. + * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. * * See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7 * @@ -337,8 +337,8 @@ type ProviderRefresh = { refresh?: { path?: string, method?: RouterMethod }, }, /** - * When refreshOnlyToken is set, only the token will be refreshed - * + * When refreshOnlyToken is set, only the token will be refreshed + * * @default true */ refreshOnlyToken?: boolean; @@ -400,7 +400,7 @@ type ProviderRefresh = { */ maxAgeInSeconds?: number, /** - * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. + * The cookie sameSite policy. Can be used as a form of csrf forgery protection. If set to `strict`, the cookie will only be passed with requests to the same 'site'. Typically, this includes subdomains. So, a sameSite: strict cookie set by app.mysite.com will be passed to api.mysite.com, but not api.othersite.com. * * See the specification here: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7 * @@ -529,6 +529,14 @@ type SessionConfig = { * @default true */ enableRefreshOnWindowFocus: boolean + /** + * A custom refresh handler to use. This can be used to implement custom session refresh logic. + * If not set, the default refresh handler will be used. + * + * @example ./src/runtime/utils/refreshHandler.ts + * @default undefined + */ + refreshHandler?: RefreshHandler; } ``` ```ts [GlobalMiddlewareOptions] diff --git a/content/2.nuxt-auth/2.configuration/5.session-config.md b/content/2.nuxt-auth/2.configuration/5.session-config.md new file mode 100644 index 00000000..9029e448 --- /dev/null +++ b/content/2.nuxt-auth/2.configuration/5.session-config.md @@ -0,0 +1,73 @@ +# Session Config + +Use this section to configure the application-side session. The following type defines the options you can use inside your auths `session`-key: + +```ts +/** + * Configuration for the application-side session. + */ +type SessionConfig = { + /** + * Whether to refresh the session every `X` milliseconds. Set this to `false` to turn it off. The session will only be refreshed if a session already exists. + * + * Setting this to `true` will refresh the session every second. + * Setting this to `false` will turn off session refresh. + * Setting this to a number `X` will refresh the session every `X` milliseconds. + * + * @example 1000 + * @default false + * + */ + enableRefreshPeriodically: number | boolean + /** + * Whether to refresh the session every time the browser window is refocused. + * + * @example false + * @default true + */ + enableRefreshOnWindowFocus: boolean + /** + * A custom refresh handler to use. This can be used to implement custom session refresh logic. + * If not set, the default refresh handler will be used. + * + * @example ./src/runtime/utils/refreshHandler.ts + * @default undefined + */ + refreshHandler?: RefreshHandler; +} +``` + +## Application side session + +Per default nuxt-auth will use the set values for `enableRefreshPeriodically` & `enableRefreshOnWindowFocus` to refresh your application-side session. If you don't provide a configuration nuxt-auth won't trigger a job that refreshes the session periodically but it will always refresh the session if the window is refocussed. + +If you set `enableRefreshPeriodically` simply to true a job will be run every second (1000ms) that will fetch your specified `getSession` endpoint. You can customize the interval if you provide a number instead of a boolean value. + +To disable the session refresh when the window is refocussed simply set `enableRefreshOnWindowFocus` to `false`. + +## Using a custom RefreshHandler + +To customize the session refreshing you can provide a refresh handler. A custom `RefreshHandler` requires an `init`- and a `destroy`-function. + +`init` will be called when the nuxt application is mounted. Here you may add event listeners and initialize custom refresh behaviour. The method will receive a `RefreshHandlerConfig`. The type consists of `enableRefreshPeriodically` & `enableRefreshOnWindowFocus`. + +`destroy` will be called when your app is unmounted. Here you may run your clean up routine e.g. to remove your event listeners. + +```ts +export type RefreshHandler = { + /** + * Initializes the refresh handler with the given configuration. + * init will be called inside app:mouted lifecycle hook. + * + * @param config The configuration to use for the refresh handler. + */ + init: (config: RefreshHandlerConfig) => void; + + /** + * Handles cleanup of the refresh handler. This method will be called when the app is destroyed. + */ + destroy: () => void; +}; +``` + +To get an idea the `defaultRefreshHandler` could be useful.