[feat] application versioning and update detection support

documentation/docs/05-modules.md

@@ -71,6 +71,8 @@ The stores themselves attach to the correct context at the point of subscription
 - `page` contains an object with the current [`url`](https://developer.mozilla.org/en-US/docs/Web/API/URL), [`params`](#loading-input-params), [`stuff`](#loading-output-stuff), [`status`](#loading-output-status) and [`error`](#loading-output-error).
 - `session` is a [writable store](https://svelte.dev/tutorial/writable-stores) whose initial value is whatever was returned from [`getSession`](#hooks-getsession). It can be written to, but this will _not_ cause changes to persist on the server — this is something you must implement yourself.
 
+- `updated` is a [writable store](https://svelte.dev/tutorial/writable-stores) whose initial value is false. The app's version will be checked every minute for changes, setting the value to true if the version does not match the version at the time the store was created. It can be written to when custom logic is required to detect updates. There is a `check` function to force the version check immediately, returning the result.
+
 ### $lib
 
 This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`]. It allows you to access common components and utility modules without `../../../../` nonsense.

documentation/docs/14-configuration.md

@@ -19,7 +19,10 @@ const config = {
 		appDir: '_app',
 		browser: {
 			hydrate: true,
-			router: true
+			router: {
+				enabled: true,
+				onError: 'fail'
+			},
 		},
 		csp: {
 			mode: 'auto',

packages/kit/src/core/adapt/prerender/fixtures/large-page/input.html

@@ -1732,7 +1732,7 @@ <h3 id="modules-$app-stores">$app/stores</h3>
 						<ul>
 							<li>
 								<code>getStores</code> is a convenience function around <code>getContext</code> that
-								returns <code>{ navigating, page, session }</code>. This needs to be called at the
+								returns <code>{ navigating, page, session, updating }</code>. This needs to be called at the
 								top-level or synchronously during component or page initialisation.
 							</li>
 						</ul>
@@ -1786,6 +1786,16 @@ <h3 id="modules-$app-stores">$app/stores</h3>
 								>. It can be written to, but this will <em>not</em> cause changes to persist on the
 								server — this is something you must implement yourself.
 							</li>
+							<li>
+								<code>updating</code> is a
+								<a
+									href="https://svelte.dev/tutorial/writable-stores"
+									target="_blank"
+									rel="noopener noreferrer"
+									>writable store</a
+								>
+								whose initial value is false. The app's version will be checked every minute for changes, setting the value to true if the version does not match the version at the time the store was created. It can be written to when custom logic is required to detect updates. There is a <code>check</code> function to force the version check immediately, returning the result.
+							</li>
 						</ul>
 						<h3 id="modules-$lib">$lib</h3>
 						<p>

packages/kit/src/core/adapt/prerender/fixtures/large-page/output.json

@@ -90,6 +90,7 @@
 	"#loading-output-stuff",
 	"https://svelte.dev/tutorial/writable-stores",
 	"#hooks-getsession",
+	"https://svelte.dev/tutorial/writable-stores",
 	"#service-workers",
 	"#configuration",
 	"#configuration",

packages/kit/src/core/build/build_client.js

@@ -29,6 +29,8 @@ export async function build_client({
 	output_dir,
 	client_entry_file
 }) {
+	if (!process.env.VITE_APP_VERSION) process.env.VITE_APP_VERSION = new Date().toISOString();
+
 	create_app({
 		manifest_data,
 		output: `${SVELTE_KIT}/generated`,
@@ -105,6 +107,12 @@ export async function build_client({
 	const entry_css = new Set();
 	find_deps(entry, vite_manifest, entry_js, entry_css);
 
+	fs.writeFileSync(
+		`${client_out_dir}/version.json`,
+		JSON.stringify(process.env.VITE_APP_VERSION),
+		'utf-8'
+	);
+
 	return {
 		assets,
 		chunks,

packages/kit/src/core/build/build_server.js

@@ -88,7 +88,10 @@ export class App {
 			read,
 			root,
 			service_worker: ${has_service_worker ? "base + '/service-worker.js'" : 'null'},
-			router: ${s(config.kit.browser.router)},
+			router: {
+				enabled: ${s(config.kit.browser.router.enabled)},
+				onError: ${s(config.kit.browser.router.onError)}
+			},
 			target: ${s(config.kit.target)},
 			template,
 			template_contains_nonce: ${template.includes('%svelte.nonce%')},

packages/kit/src/core/config/index.spec.js

@@ -16,7 +16,10 @@ const get_defaults = (prefix = '') => ({
 		appDir: '_app',
 		browser: {
 			hydrate: true,
-			router: true
+			router: {
+				enabled: true,
+				onError: 'fail'
+			}
 		},
 		csp: {
 			mode: 'auto',

packages/kit/src/core/config/options.js

@@ -59,7 +59,13 @@ const options = object(
 
 			browser: object({
 				hydrate: boolean(true),
-				router: boolean(true)
+				router: object({
+					enabled: boolean(true),
+					onError: validate('fail', (input, keypath) => {
+						if (['reload', 'fail'].includes(input)) return input;
+						throw new Error(`${keypath} should be either "reload" or "fail"`);
+					})
+				})
 			}),
 
 			csp: object({

packages/kit/src/runtime/app/env.js

@@ -14,5 +14,9 @@ export const mode = import.meta.env.MODE;
  * @type {import('$app/env').amp}
  */
 export const amp = !!import.meta.env.VITE_SVELTEKIT_AMP;
+/**
+ * @type {import('$app/env').version}
+ */
+export const version = import.meta.env.VITE_APP_VERSION;
 
 export { prerendering } from '../env.js';

packages/kit/src/runtime/app/stores.js

@@ -32,7 +32,8 @@ export const getStores = () => {
 				subscribe: stores.navigating.subscribe
 			};
 		},
-		session: stores.session
+		session: stores.session,
+		updated: stores.updated
 	};
 };
 
@@ -77,3 +78,21 @@ export const session = {
 	set: () => throw_error('set'),
 	update: () => throw_error('update')
 };
+
+/** @type {typeof import('$app/stores').updated} */
+export const updated = {
+	subscribe(fn) {
+		const store = getStores().updated;
+
+		if (browser) {
+			updated.set = store.set;
+			updated.update = store.update;
+			updated.check = store.check;
+		}
+
+		return store.subscribe(fn);
+	},
+	set: () => throw_error('set'),
+	update: () => throw_error('update'),
+	check: () => throw_error('check')
+};

packages/kit/src/runtime/client/renderer.js

@@ -6,6 +6,7 @@ import { normalize } from '../load.js';
 
 /**
  * @typedef {import('types/internal').CSRComponent} CSRComponent
+ * @typedef {import('types/config').RouteOnErrorValue} RouteOnErrorValue
  * @typedef {{ from: URL; to: URL }} Navigating
  */
 
@@ -39,6 +40,44 @@ function notifiable_store(value) {
 	return { notify, set, subscribe };
 }
 
+/**
+ * @param {any} value
+ * @param {(set: (new_value: any) => void) => any} fn
+ * @param {number | undefined} interval
+ */
+function checkable_store(value, fn, interval) {
+	const { set, update, subscribe } = writable(value);
+
+	setInterval(() => {
+		fn(set);
+	}, interval);
+
+	return {
+		set,
+		update,
+		subscribe,
+		check: () => fn(set)
+	};
+}
+
+/**
+ * @returns {Promise<boolean>}
+ */
+async function has_version_changed() {
+	if (import.meta.env.DEV) return false;
+
+	const headers = new Headers();
+	headers.append('pragma', 'no-cache');
+	headers.append('cache-control', 'no-cache');
+
+	const current_version = import.meta.env.VITE_APP_VERSION;
+	const new_version = await fetch('_app/version.json', { headers })
+		.then((res) => res.json())
+		.catch(() => undefined);
+
+	return new_version && current_version && new_version !== current_version;
+}
+
 /**
  * @param {RequestInfo} resource
  * @param {RequestInit} [opts]
@@ -108,7 +147,17 @@ export class Renderer {
 			url: notifiable_store({}),
 			page: notifiable_store({}),
 			navigating: writable(/** @type {Navigating | null} */ (null)),
-			session: writable(session)
+			session: writable(session),
+			updated: checkable_store(
+				false,
+				(set) => {
+					return has_version_changed().then((changed) => {
+						if (changed) set(true);
+						return changed;
+					});
+				},
+				300000
+			)
 		};
 
 		this.$session = null;
@@ -228,7 +277,7 @@ export class Renderer {
 	 * @param {import('./types').NavigationInfo} info
 	 * @param {string[]} chain
 	 * @param {boolean} no_cache
-	 * @param {{hash?: string, scroll: { x: number, y: number } | null, keepfocus: boolean}} [opts]
+	 * @param {{hash?: string, scroll: { x: number, y: number } | null, keepfocus: boolean, onError: RouteOnErrorValue}} [opts]
 	 */
 	async handle_navigation(info, chain, no_cache, opts) {
 		if (this.started) {
@@ -245,10 +294,11 @@ export class Renderer {
 	 * @param {import('./types').NavigationInfo} info
 	 * @param {string[]} chain
 	 * @param {boolean} no_cache
-	 * @param {{hash?: string, scroll: { x: number, y: number } | null, keepfocus: boolean}} [opts]
+	 * @param {{hash?: string, scroll: { x: number, y: number } | null, keepfocus: boolean, onError: RouteOnErrorValue}} [opts]
 	 */
 	async update(info, chain, no_cache, opts) {
 		const token = (this.token = {});
+		const onError = opts?.onError || 'fail';
 		let navigation_result = await this._get_navigation_result(info, no_cache);
 
 		// abort if user navigated during update
@@ -274,6 +324,12 @@ export class Renderer {
 					location.href = new URL(navigation_result.redirect, location.href).href;
 				}
 
+				return;
+			}
+		} else if (navigation_result.props?.page?.status >= 400 && onError !== 'fail') {
+			const updated = await this.stores.updated.check();
+			if (updated) {
+				location.href = info.url.href;
 				return;
 			}
 		}

packages/kit/src/runtime/client/router.js

@@ -35,10 +35,11 @@ export class Router {
 	 *    base: string;
 	 *    routes: import('types/internal').CSRRoute[];
 	 *    trailing_slash: import('types/internal').TrailingSlash;
-	 *    renderer: import('./renderer').Renderer
+	 *    renderer: import('./renderer').Renderer;
+	 *    onError?: import('types/config').RouteOnErrorValue;
 	 * }} opts
 	 */
-	constructor({ base, routes, trailing_slash, renderer }) {
+	constructor({ base, routes, trailing_slash, renderer, onError }) {
 		this.base = base;
 		this.routes = routes;
 		this.trailing_slash = trailing_slash;
@@ -49,6 +50,9 @@ export class Router {
 		this.renderer = renderer;
 		renderer.router = this;
 
+		/** @type {import('types/config').RouteOnErrorValue} */
+		this.onError = onError || 'fail';
+
 		this.enabled = true;
 
 		// make it possible to reset focus
@@ -407,7 +411,8 @@ export class Router {
 
 		await this.renderer.handle_navigation(info, chain, false, {
 			scroll,
-			keepfocus
+			keepfocus,
+			onError: this.onError
 		});
 
 		this.navigating--;

packages/kit/src/runtime/client/start.js

@@ -14,7 +14,10 @@ import { set_paths } from '../paths.js';
  *   },
  *   target: Node;
  *   session: any;
- *   route: boolean;
+ *   route: {
+ * 	   enabled: boolean;
+ *     onError?: import('types/config').RouteOnErrorValue;
+ *   },
  *   spa: boolean;
  *   trailing_slash: import('types/internal').TrailingSlash;
  *   hydrate: {
@@ -38,14 +41,16 @@ export async function start({ paths, target, session, route, spa, trailing_slash
 		session
 	});
 
-	const router = route
-		? new Router({
-				base: paths.base,
-				routes,
-				trailing_slash,
-				renderer
-		  })
-		: null;
+	const router =
+		route && route.enabled
+			? new Router({
+					base: paths.base,
+					routes,
+					trailing_slash,
+					renderer,
+					onError: route.onError
+			  })
+			: null;
 
 	init({ router, renderer });
 	set_paths(paths);

packages/kit/src/runtime/server/page/render.js

@@ -80,12 +80,23 @@ export async function render_response({
 
 		const session = writable($session);
 
+		const updated = () => {
+			const { set, update, subscribe } = writable(false);
+			return {
+				set,
+				update,
+				subscribe,
+				check: () => {}
+			};
+		};
+
 		/** @type {Record<string, any>} */
 		const props = {
 			stores: {
 				page: writable(null),
 				navigating: writable(null),
-				session
+				session,
+				updated
 			},
 			page: {
 				url: state.prerender ? create_prerendering_url_proxy(url) : url,
@@ -155,7 +166,10 @@ export async function render_response({
 			session: ${try_serialize($session, (error) => {
 				throw new Error(`Failed to serialize session data: ${error.message}`);
 			})},
-			route: ${!!page_config.router},
+			route: {
+				enabled: ${!!page_config.router},
+				onError: ${s(options.router.onError)}
+			},
 			spa: ${!ssr},
 			trailing_slash: ${s(options.trailing_slash)},
 			hydrate: ${ssr && page_config.hydrate ? `{

packages/kit/src/runtime/server/page/respond.js

@@ -250,7 +250,7 @@ function get_page_config(leaf, options) {
 	}
 
 	return {
-		router: 'router' in leaf ? !!leaf.router : options.router,
+		router: 'router' in leaf ? !!leaf.router : options.router.enabled,
 		hydrate: 'hydrate' in leaf ? !!leaf.hydrate : options.hydrate
 	};
 }

packages/kit/src/runtime/server/page/respond_with_error.js

@@ -65,7 +65,7 @@ export async function respond_with_error({ event, options, state, $session, stat
 			$session,
 			page_config: {
 				hydrate: options.hydrate,
-				router: options.router
+				router: options.router.enabled
 			},
 			stuff: error_loaded.stuff,
 			status,