Document and support the established naming convention for config opts

This change:
* Rename `ConfigOptions` to `IConfigOptions` to match code convention/style, plus move it to a dedicated file
* Update comments and surrounding documentation
* Define every single documented option (from element-web's config.md)
* Enable a linter to enforce the convention
* Invent a translation layer for a different change to use
* No attempt to fix build errors from doing this (at this stage)

Author: turt2live

src/@types/common.ts

@@ -41,3 +41,10 @@ export type RecursivePartial<T> = {
         T[P] extends object ? RecursivePartial<T[P]> :
             T[P];
 };
+
+// Condensed but also expanded version of https://stackoverflow.com/a/60206860
+export type KeysOfStrictType<Input, SearchType> = {
+    [P in keyof Input]: Input[P] extends SearchType
+        ? (SearchType extends Input[P] ? P : never)
+        : never;
+}[keyof Input];

src/@types/global.d.ts

@@ -52,7 +52,7 @@ import { ConsoleLogger, IndexedDBLogStore } from "../rageshake/rageshake";
 import ActiveWidgetStore from "../stores/ActiveWidgetStore";
 import { Skinner } from "../Skinner";
 import AutoRageshakeStore from "../stores/AutoRageshakeStore";
-import { ConfigOptions } from "../SdkConfig";
+import { IConfigOptions } from "../IConfigOptions";
 
 /* eslint-disable @typescript-eslint/naming-convention */
 
@@ -63,7 +63,7 @@ declare global {
         Olm: {
             init: () => Promise<void>;
         };
-        mxReactSdkConfig: ConfigOptions;
+        mxReactSdkConfig: IConfigOptions;
 
         // Needed for Safari, unknown to TypeScript
         webkitAudioContext: typeof AudioContext;

src/IConfigOptions.ts

@@ -0,0 +1,143 @@
+/*
+Copyright 2016 OpenMarket Ltd
+Copyright 2019 - 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { IClientWellKnown } from "matrix-js-sdk/src/matrix";
+
+// Convention decision: All config options are lower_snake_case
+// We use an isolated file for the interface so we can mess around with the eslint options.
+
+/* eslint-disable camelcase */
+/* eslint @typescript-eslint/naming-convention: ["error", { "selector": "property", "format": ["snake_case"] } ] */
+
+// see element-web config.md for non-developer docs
+export interface IConfigOptions {
+    // dev note: while true that this is arbitrary JSON, it's valuable to enforce that all
+    // config options are documented for "find all usages" sort of searching.
+    // [key: string]: any;
+
+    // Properties of this interface are roughly grouped by their subject matter, such as
+    // "instance customisation", "login stuff", "branding", etc. Use blank lines to denote
+    // a logical separation of properties, but keep similar ones near each other.
+
+    // Exactly one of the following must be supplied
+    default_server_config?: IClientWellKnown; // copy/paste of client well-known
+    default_server_name?: string; // domain to do well-known lookup on
+    default_hs_url?: string; // http url
+
+    default_is_url?: string; // used in combination with default_hs_url, but for the identity server
+
+    disable_custom_urls?: boolean;
+    disable_guests?: boolean;
+    disable_login_language_selector?: boolean;
+    disable_3pid_login?: boolean;
+
+    brand?: string;
+    branding?: {
+        welcome_background_url?: string;
+        auth_header_logo_url?: string;
+        auth_footer_links?: {text: string, url: string}[];
+    };
+
+    map_style_url?: string; // for location-shared maps
+
+    embedded_pages?: {
+        welcome_url?: string;
+        home_url?: string;
+        login_for_welcome?: boolean;
+    };
+
+    permalink_prefix?: string;
+
+    update_base_url?: string;
+    desktop_builds?: {
+        available: boolean;
+        logo: string; // url
+        url: string; // download url
+    };
+    mobile_builds?: {
+        ios?: string; // download url
+        android?: string; // download url
+        fdroid?: string; // download url
+    };
+
+    mobile_guide_toast?: boolean;
+
+    default_theme?: "light" | "dark" | string; // custom themes are strings
+    default_country_code?: string; // ISO 3166 alpha2 country code
+    default_federate?: boolean;
+    default_device_display_name?: string; // for device naming on login+registration
+
+    setting_defaults?: Record<string, any>; // <SettingName, Value>
+
+    integrations_ui_url?: string;
+    integrations_rest_url?: string;
+    integrations_widgets_urls?: string[];
+
+    show_labs_settings?: boolean;
+    features?: Record<string, boolean>; // <FeatureName, EnabledBool>
+
+    bug_report_endpoint_url?: string; // omission disables bug reporting
+    uisi_autorageshake_app?: string;
+    sentry?: {
+        dsn: string;
+        environment?: string; // "production", etc
+    };
+
+    audio_stream_url?: string;
+    jitsi?: {
+        preferred_domain: string;
+    };
+    voip?: {
+        obey_asserted_identity?: boolean; // MSC3086
+    };
+
+    logout_redirect_url?: string;
+
+    // sso_immediate_redirect is deprecated in favour of sso_redirect_options.immediate
+    sso_immediate_redirect?: boolean;
+    sso_redirect_options?: ISsoRedirectOptions;
+
+    custom_translations_url?: string;
+
+    report_event?: {
+        admin_message_md: string; // message for how to contact the server owner when reporting an event
+    };
+
+    welcome_user_id?: string;
+
+    room_directory?: {
+        servers: string[];
+    };
+
+    // piwik (matomo) is deprecated in favour of posthog
+    piwik?: false | {
+        url: string; // piwik instance
+        site_id: string | number; // TODO: @@TR Typed correctly?
+        policy_url: string; // cookie policy
+        whitelisted_hs_urls: string[];
+    };
+    posthog?: {
+        project_api_key: string;
+        api_host: string; // hostname
+    };
+    analytics_owner?: string; // defaults to `brand`
+}
+
+export interface ISsoRedirectOptions {
+    immediate?: boolean;
+    on_welcome_page?: boolean;
+}

src/SdkConfig.ts

@@ -1,6 +1,6 @@
 /*
 Copyright 2016 OpenMarket Ltd
-Copyright 2019 - 2021 The Matrix.org Foundation C.I.C.
+Copyright 2019 - 2022 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -15,61 +15,62 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-export interface ISsoRedirectOptions {
-    immediate?: boolean;
-    on_welcome_page?: boolean; // eslint-disable-line camelcase
-}
-
-/* eslint-disable camelcase */
-export interface ConfigOptions {
-    [key: string]: any;
-
-    logout_redirect_url?: string;
+import { Optional } from "matrix-events-sdk";
 
-    // sso_immediate_redirect is deprecated in favour of sso_redirect_options.immediate
-    sso_immediate_redirect?: boolean;
-    sso_redirect_options?: ISsoRedirectOptions;
-
-    custom_translations_url?: string;
-}
-/* eslint-enable camelcase*/
+import { SnakedObject } from "./utils/SnakedObject";
+import { IConfigOptions, ISsoRedirectOptions } from "./IConfigOptions";
+import { KeysOfStrictType } from "./@types/common";
 
-export const DEFAULTS: ConfigOptions = {
-    // Brand name of the app
+// see element-web config.md for docs, or the IConfigOptions interface for dev docs
+export const DEFAULTS: Partial<IConfigOptions> = {
     brand: "Element",
-    // URL to a page we show in an iframe to configure integrations
     integrations_ui_url: "https://scalar.vector.im/",
-    // Base URL to the REST interface of the integrations server
     integrations_rest_url: "https://scalar.vector.im/api",
-    // Where to send bug reports. If not specified, bugs cannot be sent.
     bug_report_endpoint_url: null,
-    // Jitsi conference options
     jitsi: {
-        // Default conference domain
-        preferredDomain: "meet.element.io",
+        preferred_domain: "meet.element.io",
     },
-    desktopBuilds: {
+    desktop_builds: {
         available: true,
         logo: require("../res/img/element-desktop-logo.svg").default,
         url: "https://element.io/get-started",
     },
 };
 
 export default class SdkConfig {
-    private static instance: ConfigOptions;
+    private static instance: IConfigOptions;
+    private static fallback: SnakedObject<IConfigOptions>;
 
-    private static setInstance(i: ConfigOptions) {
+    private static setInstance(i: IConfigOptions) {
         SdkConfig.instance = i;
+        SdkConfig.fallback = new SnakedObject(i);
 
         // For debugging purposes
         window.mxReactSdkConfig = i;
     }
 
-    public static get() {
-        return SdkConfig.instance || {};
+    public static get(): IConfigOptions;
+    public static get<K extends keyof IConfigOptions>(key: K, altCaseName?: string): IConfigOptions[K];
+    public static get<K extends keyof IConfigOptions = never>(
+        key?: K, altCaseName?: string,
+    ): IConfigOptions | IConfigOptions[K] {
+        if (key === undefined) return SdkConfig.instance || {};
+        return SdkConfig.fallback.get(key, altCaseName);
+    }
+
+    public static getObject<K extends KeysOfStrictType<IConfigOptions, object>>(
+        key: K, altCaseName?: string,
+    ): Optional<SnakedObject<IConfigOptions[K]>> {
+        const val = SdkConfig.get(key, altCaseName);
+        if (val !== null && val !== undefined) {
+            return new SnakedObject(val);
+        }
+
+        // return the same type for sensitive callers (some want `undefined` specifically)
+        return val === undefined ? undefined : null;
     }
 
-    public static put(cfg: ConfigOptions) {
+    public static put(cfg: IConfigOptions) {
         const defaultKeys = Object.keys(DEFAULTS);
         for (let i = 0; i < defaultKeys.length; ++i) {
             if (cfg[defaultKeys[i]] === undefined) {
@@ -83,14 +84,14 @@ export default class SdkConfig {
         SdkConfig.setInstance({});
     }
 
-    public static add(cfg: ConfigOptions) {
+    public static add(cfg: IConfigOptions) {
         const liveConfig = SdkConfig.get();
         const newConfig = Object.assign({}, liveConfig, cfg);
         SdkConfig.put(newConfig);
     }
 }
 
-export function parseSsoRedirectOptions(config: ConfigOptions): ISsoRedirectOptions {
+export function parseSsoRedirectOptions(config: IConfigOptions): ISsoRedirectOptions {
     // Ignore deprecated options if the config is using new ones
     if (config.sso_redirect_options) return config.sso_redirect_options;
 

src/utils/SnakedObject.ts

@@ -0,0 +1,36 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export function snakeToCamel(s: string): string {
+    return s.replace(/._./g, v => `${v[0]}${v[2].toUpperCase()}`);
+}
+
+export class SnakedObject<T = Record<string, any>> {
+    public constructor(private obj: T) {
+    }
+
+    public get<K extends string & keyof T>(key: K, altCaseName?: string): T[K] {
+        const val = this.obj[key];
+        if (val !== undefined) return val;
+
+        return this.obj[altCaseName ?? snakeToCamel(key)];
+    }
+
+    // Make JSON.stringify() pretend that everything is fine
+    public toJSON() {
+        return this.obj;
+    }
+}

src/utils/pages.ts

@@ -14,9 +14,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { ConfigOptions } from "../SdkConfig";
+import { IConfigOptions } from "../IConfigOptions";
 
-export function getHomePageUrl(appConfig: ConfigOptions): string | null {
+export function getHomePageUrl(appConfig: IConfigOptions): string | null {
     const pagesConfig = appConfig.embeddedPages;
     let pageUrl = pagesConfig?.homeUrl;
 
@@ -30,7 +30,7 @@ export function getHomePageUrl(appConfig: ConfigOptions): string | null {
     return pageUrl;
 }
 
-export function shouldUseLoginForWelcome(appConfig: ConfigOptions): boolean {
+export function shouldUseLoginForWelcome(appConfig: IConfigOptions): boolean {
     const pagesConfig = appConfig.embeddedPages;
     return pagesConfig?.loginForWelcome === true;
 }