Added RouteSettings type model, store contract and in-memory adapter (#28821)

ref HKG-1825

- RouteSettings is the canonical domain model for routes.yaml — a flat typed structure that the new RouteSettingsService will use instead of the untyped objects that validate.js produces today 
- Domain model stores what the user wrote ({slug} notation, short-form data, templates as string[]) so round-tripping through any future store is lossless — no expansion or normalisation at the storage layer 
- Store contract (get/replace) defines the interface that FileStore and GCS will implement — foundation for swapping storage backends 
- Contract tests verify immutability semantics so no future store implementation can leak internal references to callers

Author: vershwal

ghost/core/core/server/adapters/route-settings/RouteSettingsStoreBase.d.ts

@@ -0,0 +1,18 @@
+// PascalCase mirrors the runtime `RouteSettingsStoreBase.js` so the TS adapter
+// can default-import via the matching declaration file.
+import type {RouteSettings} from '../../services/route-settings/route-settings-parser';
+
+/**
+ * Concurrent `replace` calls have no ordering guarantee — serialize
+ * externally if that matters.
+ */
+export interface RouteSettingsStore {
+    get(): Promise<RouteSettings>;
+    replace(settings: RouteSettings): Promise<void>;
+}
+
+declare class RouteSettingsStoreBase {
+    readonly requiredFns: ReadonlyArray<string>;
+}
+
+export default RouteSettingsStoreBase;

ghost/core/core/server/adapters/route-settings/RouteSettingsStoreBase.js

@@ -0,0 +1,8 @@
+module.exports = class RouteSettingsStoreBase {
+    constructor() {
+        Object.defineProperty(this, 'requiredFns', {
+            value: ['get', 'replace'],
+            writable: false
+        });
+    }
+};

ghost/core/core/server/services/route-settings/route-settings-parser.ts

@@ -0,0 +1,74 @@
+export type DataShortFormResource = 'tag' | 'page' | 'post' | 'author';
+export type DataLongFormResource = 'tags' | 'posts' | 'pages' | 'authors';
+
+export type DataShortForm = `${DataShortFormResource}.${string}`;
+
+export interface DataReadEntry {
+    type: 'read';
+    resource: DataLongFormResource;
+    slug: string;
+    redirect?: boolean;
+    include?: string;
+    visibility?: string;
+    status?: string;
+}
+
+export interface DataBrowseEntry {
+    type: 'browse';
+    resource: DataLongFormResource;
+    filter?: string;
+    limit?: number | 'all';
+    order?: string;
+    include?: string;
+    fields?: string;
+    visibility?: string;
+    status?: string;
+    page?: number;
+}
+
+export type DataLongFormEntry = DataReadEntry | DataBrowseEntry;
+export type DataEntry = DataShortForm | DataLongFormEntry;
+export type RouteData = DataShortForm | Record<string, DataEntry>;
+
+interface RouteBase {
+    path: string;
+    templates?: string[];
+    data?: RouteData;
+}
+
+export interface ChannelRoute extends RouteBase {
+    type: 'channel';
+    filter?: string;
+    order?: string;
+    limit?: number | 'all';
+    rss: boolean;
+}
+
+export interface TemplateRoute extends RouteBase {
+    type: 'template';
+    contentType?: string;
+}
+
+export type Route = ChannelRoute | TemplateRoute;
+
+export interface CollectionConfig {
+    path: string;
+    permalink: string;
+    templates?: string[];
+    filter?: string;
+    order?: string;
+    limit?: number | 'all';
+    rss?: boolean;
+    data?: RouteData;
+}
+
+export interface TaxonomyConfig {
+    tag?: string;
+    author?: string;
+}
+
+export interface RouteSettings {
+    routes: Route[];
+    collections: CollectionConfig[];
+    taxonomies: TaxonomyConfig;
+}

ghost/core/test/unit/server/adapters/route-settings/helpers/in-memory-store.ts

@@ -0,0 +1,14 @@
+import type {RouteSettings} from '../../../../../../core/server/services/route-settings/route-settings-parser';
+import type {RouteSettingsStore} from '../../../../../../core/server/adapters/route-settings/RouteSettingsStoreBase';
+
+export class InMemoryStore implements RouteSettingsStore {
+    private settings: RouteSettings = {routes: [], collections: [], taxonomies: {}};
+
+    async get(): Promise<RouteSettings> {
+        return structuredClone(this.settings);
+    }
+
+    async replace(settings: RouteSettings): Promise<void> {
+        this.settings = structuredClone(settings);
+    }
+}

ghost/core/test/unit/server/adapters/route-settings/helpers/store-contract.ts

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+
+import type {RouteSettings} from '../../../../../../core/server/services/route-settings/route-settings-parser';
+import type {RouteSettingsStore} from '../../../../../../core/server/adapters/route-settings/RouteSettingsStoreBase';
+
+interface ContractOptions {
+    createStore: () => RouteSettingsStore | Promise<RouteSettingsStore>;
+}
+
+const emptySettings = (): RouteSettings => ({routes: [], collections: [], taxonomies: {}});
+
+const sampleSettings = (): RouteSettings => ({
+    routes: [
+        {type: 'template', path: '/about/', templates: ['about']}
+    ],
+    collections: [
+        {
+            path: '/',
+            permalink: '/{slug}/',
+            templates: ['index'],
+            data: {featured: {resource: 'posts', type: 'browse', filter: 'featured:true'}}
+        }
+    ],
+    taxonomies: {
+        tag: '/tag/{slug}/'
+    }
+});
+
+export function runStoreContract({createStore}: ContractOptions): void {
+    describe('RouteSettingsStore contract', function () {
+        let store: RouteSettingsStore;
+
+        beforeEach(async function () {
+            store = await createStore();
+        });
+
+        describe('get', function () {
+            it('returns settings that callers cannot mutate in place', async function () {
+                await store.replace(sampleSettings());
+
+                const firstRead = await store.get();
+                firstRead.routes.push({type: 'template', path: '/x/', templates: ['x']});
+                firstRead.collections[0].permalink = '/mutated/';
+
+                assert.deepEqual(await store.get(), sampleSettings());
+            });
+        });
+
+        describe('replace', function () {
+            it('persists settings so get returns the same RouteSettings', async function () {
+                const settings = sampleSettings();
+
+                await store.replace(settings);
+
+                assert.deepEqual(await store.get(), settings);
+            });
+
+            it('overwrites previously stored settings rather than merging', async function () {
+                await store.replace(sampleSettings());
+                await store.replace({
+                    routes: [],
+                    collections: [{path: '/blog/', permalink: '/blog/{slug}/', templates: ['index']}],
+                    taxonomies: {}
+                });
+
+                assert.deepEqual(await store.get(), {
+                    routes: [],
+                    collections: [{path: '/blog/', permalink: '/blog/{slug}/', templates: ['index']}],
+                    taxonomies: {}
+                });
+            });
+
+            it('clears all settings when called with empty settings', async function () {
+                await store.replace(sampleSettings());
+                await store.replace(emptySettings());
+
+                assert.deepEqual(await store.get(), emptySettings());
+            });
+
+            it('does not retain a reference to the input (caller mutations do not leak)', async function () {
+                const settings = sampleSettings();
+
+                await store.replace(settings);
+                settings.routes.push({type: 'template', path: '/x/', templates: ['x']});
+                settings.taxonomies.tag = '/mutated/';
+
+                assert.deepEqual(await store.get(), sampleSettings());
+            });
+        });
+    });
+}

ghost/core/test/unit/server/adapters/route-settings/in-memory-store.test.ts

@@ -0,0 +1,8 @@
+import {InMemoryStore} from './helpers/in-memory-store';
+import {runStoreContract} from './helpers/store-contract';
+
+describe('UNIT: InMemoryStore (validates the contract)', function () {
+    runStoreContract({
+        createStore: () => new InMemoryStore()
+    });
+});