Use & enforce snake_case naming convention on config.json settings (#…

…8062)

* 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)

* Add demo of lint rule in action

* Fix all obvious instances of SdkConfig case conflicts

* Fix tests to use SdkConfig directly

* Add docs to make unset() calling safer

* Appease the linter

* Update documentation to match snake_case_config

* Fix more instances of square brackets off SdkConfig

src/@types/common.ts

@@ -41,3 +41,11 @@ export type RecursivePartial<T> = {
         T[P] extends object ? RecursivePartial<T[P]> :
             T[P];
 };
+
+// Inspired by https://stackoverflow.com/a/60206860
+export type KeysWithObjectShape<Input> = {
+    [P in keyof Input]: Input[P] extends object
+        // Arrays are counted as objects - exclude them
+        ? (Input[P] extends Array<unknown> ? never : P)
+        : 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/Analytics.tsx

@@ -17,12 +17,15 @@ limitations under the License.
 
 import React from 'react';
 import { logger } from "matrix-js-sdk/src/logger";
+import { Optional } from "matrix-events-sdk";
 
 import { getCurrentLanguage, _t, _td, IVariables } from './languageHandler';
 import PlatformPeg from './PlatformPeg';
 import SdkConfig from './SdkConfig';
 import Modal from './Modal';
 import * as sdk from './index';
+import { SnakedObject } from "./utils/SnakedObject";
+import { IConfigOptions } from "./IConfigOptions";
 
 const hashRegex = /#\/(groups?|room|user|settings|register|login|forgot_password|home|directory)/;
 const hashVarRegex = /#\/(group|room|user)\/.*$/;
@@ -193,8 +196,12 @@ export class Analytics {
     }
 
     public canEnable() {
-        const config = SdkConfig.get();
-        return navigator.doNotTrack !== "1" && config && config.piwik && config.piwik.url && config.piwik.siteId;
+        const piwikConfig = SdkConfig.get("piwik");
+        let piwik: Optional<SnakedObject<Extract<IConfigOptions["piwik"], object>>>;
+        if (typeof piwikConfig === 'object') {
+            piwik = new SnakedObject(piwikConfig);
+        }
+        return navigator.doNotTrack !== "1" && piwik?.get("site_id");
     }
 
     /**
@@ -204,12 +211,16 @@ export class Analytics {
     public async enable() {
         if (!this.disabled) return;
         if (!this.canEnable()) return;
-        const config = SdkConfig.get();
+        const piwikConfig = SdkConfig.get("piwik");
+        let piwik: Optional<SnakedObject<Extract<IConfigOptions["piwik"], object>>>;
+        if (typeof piwikConfig === 'object') {
+            piwik = new SnakedObject(piwikConfig);
+        }
 
-        this.baseUrl = new URL("piwik.php", config.piwik.url);
+        this.baseUrl = new URL("piwik.php", piwik.get("url"));
         // set constants
         this.baseUrl.searchParams.set("rec", "1"); // rec is required for tracking
-        this.baseUrl.searchParams.set("idsite", config.piwik.siteId); // rec is required for tracking
+        this.baseUrl.searchParams.set("idsite", piwik.get("site_id")); // idsite is required for tracking
         this.baseUrl.searchParams.set("apiv", "1"); // API version to use
         this.baseUrl.searchParams.set("send_image", "0"); // we want a 204, not a tiny GIF
         // set user parameters
@@ -347,10 +358,14 @@ export class Analytics {
     public setLoggedIn(isGuest: boolean, homeserverUrl: string) {
         if (this.disabled) return;
 
-        const config = SdkConfig.get();
-        if (!config.piwik) return;
+        const piwikConfig = SdkConfig.get("piwik");
+        let piwik: Optional<SnakedObject<Extract<IConfigOptions["piwik"], object>>>;
+        if (typeof piwikConfig === 'object') {
+            piwik = new SnakedObject(piwikConfig);
+        }
+        if (!piwik) return;
 
-        const whitelistedHSUrls = config.piwik.whitelistedHSUrls || [];
+        const whitelistedHSUrls = piwik.get("whitelisted_hs_urls", "whitelistedHSUrls") || [];
 
         this.setVisitVariable('User Type', isGuest ? 'Guest' : 'Logged In');
         this.setVisitVariable('Homeserver URL', whitelistRedact(whitelistedHSUrls, homeserverUrl));
@@ -391,7 +406,12 @@ export class Analytics {
         ];
 
         // FIXME: Using an import will result in test failures
-        const cookiePolicyUrl = SdkConfig.get().piwik?.policyUrl;
+        const piwikConfig = SdkConfig.get("piwik");
+        let piwik: Optional<SnakedObject<Extract<IConfigOptions["piwik"], object>>>;
+        if (typeof piwikConfig === 'object') {
+            piwik = new SnakedObject(piwikConfig);
+        }
+        const cookiePolicyUrl = piwik?.get("policy_url");
         const ErrorDialog = sdk.getComponent('dialogs.ErrorDialog');
         const cookiePolicyLink = _t(
             "Our complete cookie policy can be found <CookiePolicyLink>here</CookiePolicyLink>.",

src/BasePlatform.ts

@@ -32,6 +32,7 @@ import { hideToast as hideUpdateToast } from "./toasts/UpdateToast";
 import { MatrixClientPeg } from "./MatrixClientPeg";
 import { idbLoad, idbSave, idbDelete } from "./utils/StorageManager";
 import { ViewRoomPayload } from "./dispatcher/payloads/ViewRoomPayload";
+import { IConfigOptions } from "./IConfigOptions";
 
 export const SSO_HOMESERVER_URL_KEY = "mx_sso_hs_url";
 export const SSO_ID_SERVER_URL_KEY = "mx_sso_is_url";
@@ -62,7 +63,7 @@ export default abstract class BasePlatform {
         this.startUpdateCheck = this.startUpdateCheck.bind(this);
     }
 
-    abstract getConfig(): Promise<{}>;
+    abstract getConfig(): Promise<IConfigOptions>;
 
     abstract getDefaultDeviceDisplayName(): string;
 

src/CallHandler.tsx

@@ -259,7 +259,7 @@ export default class CallHandler extends EventEmitter {
     }
 
     private shouldObeyAssertedfIdentity(): boolean {
-        return SdkConfig.get()['voip']?.obeyAssertedIdentity;
+        return SdkConfig.getObject("voip")?.get("obey_asserted_identity");
     }
 
     public getSupportsPstnProtocol(): boolean {

src/IConfigOptions.ts

@@ -0,0 +1,186 @@
+/*
+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";
+
+import { ValidatedServerConfig } from "./utils/AutoDiscoveryUtils";
+
+// 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
+
+    // This is intended to be overridden by app startup and not specified by the user
+    // This is also why it's allowed to have an interface that isn't snake_case
+    validated_server_config?: ValidatedServerConfig;
+
+    fallback_hs_url?: string;
+
+    disable_custom_urls?: boolean;
+    disable_guests?: boolean;
+    disable_login_language_selector?: boolean;
+    disable_3pid_login?: boolean;
+
+    brand: string;
+    branding?: {
+        welcome_background_url?: string | string[]; // chosen at random if array
+        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
+    };
+
+    widget_build_url?: string; // url called to replace jitsi/call widget creation
+    audio_stream_url?: string;
+    jitsi?: {
+        preferred_domain: string;
+    };
+    jitsi_widget?: {
+        skip_built_in_welcome_screen?: boolean;
+    };
+    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;
+        policy_url: string; // cookie policy
+        whitelisted_hs_urls: string[];
+    };
+    posthog?: {
+        project_api_key: string;
+        api_host: string; // hostname
+    };
+    analytics_owner?: string; // defaults to `brand`
+
+    // Server hosting upsell options
+    hosting_signup_link?: string; // slightly different from `host_signup`
+    host_signup?: {
+        brand?: string; // acts as the enabled flag too (truthy == show)
+
+        // Required-ness denotes when `brand` is truthy
+        cookie_policy_url: string;
+        privacy_policy_url: string;
+        terms_of_service_url: string;
+        url: string;
+        domains?: string[];
+    };
+
+    enable_presence_by_hs_url?: Record<string, boolean>; // <HomeserverName, Enabled>
+
+    terms_and_conditions_links?: { url: string, text: string }[];
+
+    latex_maths_delims?: {
+        inline?: {
+            left?: string;
+            right?: string;
+        };
+        display?: {
+            left?: string;
+            right?: string;
+        };
+    };
+
+    sync_timeline_limit?: number;
+    dangerously_allow_unsafe_and_insecure_passwords?: boolean; // developer option
+}
+
+export interface ISsoRedirectOptions {
+    immediate?: boolean;
+    on_welcome_page?: boolean;
+}

src/KeyBindingsDefaults.ts

@@ -161,7 +161,7 @@ const callBindings = (): KeyBinding[] => {
 };
 
 const labsBindings = (): KeyBinding[] => {
-    if (!SdkConfig.get()['showLabsSettings']) return [];
+    if (!SdkConfig.get("show_labs_settings")) return [];
 
     return getBindingsByCategory(CategoryName.LABS);
 };

src/Livestream.ts

@@ -21,7 +21,7 @@ import SdkConfig from "./SdkConfig";
 import { ElementWidgetActions } from "./stores/widgets/ElementWidgetActions";
 
 export function getConfigLivestreamUrl() {
-    return SdkConfig.get()["audioStreamUrl"];
+    return SdkConfig.get("audio_stream_url");
 }
 
 // Dummy rtmp URL used to signal that we want a special audio-only stream

src/PosthogAnalytics.ts

@@ -126,10 +126,10 @@ export class PosthogAnalytics {
     }
 
     constructor(private readonly posthog: PostHog) {
-        const posthogConfig = SdkConfig.get()["posthog"];
+        const posthogConfig = SdkConfig.getObject("posthog");
         if (posthogConfig) {
-            this.posthog.init(posthogConfig.projectApiKey, {
-                api_host: posthogConfig.apiHost,
+            this.posthog.init(posthogConfig.get("project_api_key"), {
+                api_host: posthogConfig.get("api_host"),
                 autocapture: false,
                 mask_all_text: true,
                 mask_all_element_attributes: true,

src/ScalarAuthClient.ts

@@ -44,8 +44,8 @@ export default class ScalarAuthClient {
 
         // We try and store the token on a per-manager basis, but need a fallback
         // for the default manager.
-        const configApiUrl = SdkConfig.get()['integrations_rest_url'];
-        const configUiUrl = SdkConfig.get()['integrations_ui_url'];
+        const configApiUrl = SdkConfig.get("integrations_rest_url");
+        const configUiUrl = SdkConfig.get("integrations_ui_url");
         this.isDefaultManager = apiUrl === configApiUrl && configUiUrl === uiUrl;
     }