Document and support the established naming convention for config opts

This change:
* Rename `ConfigOptions` to `IConfigOptions` to match code convention/style
* Update comments and surrounding documentation
* Define every single documented option (from element-web's config.md)
* Try and 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

.eslintrc.js

@@ -1,6 +1,7 @@
 module.exports = {
     plugins: [
         "matrix-org",
+        "snakecasejs", // for SdkConfig
     ],
     extends: [
         "plugin:matrix-org/babel",
@@ -15,6 +16,9 @@ module.exports = {
         LANGUAGES_FILE: "readonly",
     },
     rules: {
+        // Disable snakecase as a default (re-enabled manually by SdkConfig)
+        "snakecasejs/snakecasejs": "off",
+
         // Things we do that break the ideal style
         "no-constant-condition": "off",
         "prefer-promise-reject-errors": "off",

package.json

@@ -175,6 +175,7 @@
     "eslint-plugin-matrix-org": "^0.4.0",
     "eslint-plugin-react": "^7.28.0",
     "eslint-plugin-react-hooks": "^4.3.0",
+    "eslint-plugin-snakecasejs": "^2.2.0",
     "glob": "^7.1.6",
     "jest": "^27.4.0",
     "jest-canvas-mock": "^2.3.0",

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 "../SdkConfig";
 
 /* 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/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,14 +15,96 @@ 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
-}
+import { IClientWellKnown } from "matrix-js-sdk/src/client";
+
+import { SnakedObject } from "./utils/SnakedObject";
 
 /* eslint-disable camelcase */
-export interface ConfigOptions {
-    [key: string]: any;
+/* eslint-enable snakecasejs/snakecasejs */
+// Convention decision: All config options are lower_snake_case
+// see element-web config.md for non-developer docs
+export interface IConfigOptions { // eslint-disable-line snakecasejs/snakecasejs
+    valToEnsureLinterWorks?: never;
+
+    // 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;
 
@@ -31,45 +113,76 @@ export interface ConfigOptions {
     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 { // eslint-disable-line snakecasejs/snakecasejs
+    immediate?: boolean;
+    on_welcome_page?: boolean;
 }
+/* eslint-disable snakecasejs/snakecasejs */
 /* eslint-enable camelcase*/
 
-export const DEFAULTS: ConfigOptions = {
-    // Brand name of the app
+// see element-web config.md for docs, or the ConfigOptions 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 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 +196,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 "../SdkConfig";
 
-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;
 }

test/utils/SnakedObject-test.ts

@@ -0,0 +1,63 @@
+/*
+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.
+*/
+
+import { SnakedObject, snakeToCamel } from "../../src/utils/SnakedObject";
+
+describe('snakeToCamel', () => {
+    it('should convert snake_case to camelCase in simple scenarios', () => {
+        expect(snakeToCamel("snake_case")).toBe("snakeCase");
+        expect(snakeToCamel("snake_case_but_longer")).toBe("snakeCaseButLonger");
+        expect(snakeToCamel("numbered_123")).toBe("numbered123"); // not a thing we would see normally
+    });
+
+    // Not really something we expect to see, but it's defined behaviour of the function
+    it('should not camelCase a trailing or leading underscore', () => {
+        expect(snakeToCamel("_snake")).toBe("_snake");
+        expect(snakeToCamel("snake_")).toBe("snake_");
+        expect(snakeToCamel("_snake_case")).toBe("_snakeCase");
+        expect(snakeToCamel("snake_case_")).toBe("snakeCase_");
+    });
+
+    // Another thing we don't really expect to see, but is "defined behaviour"
+    it('should be predictable with double underscores', () => {
+        expect(snakeToCamel("__snake__")).toBe("_Snake_");
+        expect(snakeToCamel("snake__case")).toBe("snake_case");
+    });
+});
+
+describe('SnakedObject', () => {
+    /* eslint-disable camelcase*/
+    const input = {
+        snake_case: "woot",
+        snakeCase: "oh no", // ensure different value from snake_case for tests
+        camelCase: "fallback",
+    };
+    const snake = new SnakedObject(input);
+    /* eslint-enable camelcase*/
+
+    it('should prefer snake_case keys', () => {
+        expect(snake.get("snake_case")).toBe(input.snake_case);
+        expect(snake.get("snake_case", "camelCase")).toBe(input.snake_case);
+    });
+
+    it('should fall back to camelCase keys when needed', () => {
+        // @ts-ignore - we're deliberately supplying a key that doesn't exist
+        expect(snake.get("camel_case")).toBe(input.camelCase);
+
+        // @ts-ignore - we're deliberately supplying a key that doesn't exist
+        expect(snake.get("e_no_exist", "camelCase")).toBe(input.camelCase);
+    });
+});

yarn.lock

@@ -3837,6 +3837,11 @@ eslint-plugin-react@^7.28.0:
     semver "^6.3.0"
     string.prototype.matchall "^4.0.6"
 
+eslint-plugin-snakecasejs@^2.2.0:
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-snakecasejs/-/eslint-plugin-snakecasejs-2.2.0.tgz#e35bf4eee2f375a9ba79de68c96303e06f8acf86"
+  integrity sha512-vdQHT2VvzPpJHHPAVXjtyAZ/CfiJqNCa2d9kn6XMapWBN2Uio/nzL957TooNa6gumlHabBAhB5eSNmqwHgu8gA==
+
 eslint-rule-composer@^0.3.0:
   version "0.3.0"
   resolved "https://registry.yarnpkg.com/eslint-rule-composer/-/eslint-rule-composer-0.3.0.tgz#79320c927b0c5c0d3d3d2b76c8b4a488f25bbaf9"