🧑‍💻(DX) Use of debug flags

Debug flags allow the application to behave differently.
They can be set in various ways
and allow to debug certain aspects of the application.
They can ease development
and help debug errors in production environments.

Debug flags need to be enabled with debug namespace(s).
e.g."feature:language" would instruct the application
to be more verbose about its language features.
e.g. "no-cache" would instruct the application
to avoid caching entirely.

The value for the debug configuration
is always a string
with debug namespaces separated by comma.

Signed-off-by: Robin Weber <[email protected]>

Author: rvveber

src/backend/impress/settings.py

@@ -58,7 +58,14 @@ class Base(Configuration):
     * DB_USER
     """
 
-    DEBUG = False
+    DEBUG_RAW = values.Value(
+        default=False,
+        environ_name="DEBUG",
+        environ_prefix=None,
+    )
+    DEBUG_NAMESPACES = DEBUG_RAW.split(",") if isinstance(DEBUG_RAW, str) else []
+    DEBUG = bool(DEBUG_RAW)
+
     USE_SWAGGER = False
 
     API_VERSION = "v1.0"
@@ -761,6 +768,9 @@ def post_setup(cls):
                 "OIDC_ALLOW_DUPLICATE_EMAILS cannot be set to True simultaneously. "
             )
 
+        if cls.DEBUG and "no-cache" in cls.DEBUG_NAMESPACES:
+            cls.THEME_CUSTOMIZATION_CACHE_TIMEOUT = 0
+
 
 class Build(Base):
     """Settings used when the application is built.
@@ -795,6 +805,17 @@ class Development(Base):
     CSRF_TRUSTED_ORIGINS = ["http://localhost:8072", "http://localhost:3000"]
     DEBUG = True
 
+    # Enable debug namespaces as needed
+    #
+    # DEBUG_NAMESPACES = [
+    #     'no-cache',
+    #     'features:language'
+    # ]
+    #
+    # They can be enabled in all environments
+    # via DEBUG environment variable
+    #   DEBUG="features:language,no-cache,..."
+
     SESSION_COOKIE_NAME = "impress_sessionid"
 
     USE_SWAGGER = True

src/frontend/apps/impress/src/core/AppProvider.tsx

@@ -17,13 +17,16 @@ import { ConfigProvider } from './config/';
  * QueryClient:
  *  - defaultOptions:
  *    - staleTime:
- *      - global cache duration - we decided 3 minutes
- *      - It can be overridden to each query
+ *      - global time until cache is considered stale and will be refetched in the background
+ *        - instant if debug flag "no-cache" active - 3 minutes otherwise
+ *    - gcTime:
+ *      - global time until cache is purged from the persister and needs to be renewed
+ *        - since its cached in localStorage, we can set it to a long time (48h)
  */
 const defaultOptions = {
   queries: {
     staleTime: debug.enabled('no-cache') ? 0 : 1000 * 60 * 3, // 3 minutes
-    staleTime: 1000 * 60 * 3,
+    gcTime: debug.enabled('no-cache') ? 0 : 1000 * 60 * 60 * 48, // 48 hours
     retry: 1,
   },
 };

src/frontend/apps/impress/src/core/config/api/useConfig.tsx

@@ -1,4 +1,5 @@
 import { useQuery } from '@tanstack/react-query';
+import debug from 'debug';
 
 import { APIError, errorCauses, fetchAPI } from '@/api';
 import { Theme } from '@/cunningham/';
@@ -19,45 +20,24 @@ interface ConfigResponse {
   SENTRY_DSN?: string;
 }
 
-const LOCAL_STORAGE_KEY = 'docs_config';
-
-function getCachedTranslation() {
-  try {
-    const jsonString = localStorage.getItem(LOCAL_STORAGE_KEY);
-    return jsonString ? (JSON.parse(jsonString) as ConfigResponse) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function setCachedTranslation(translations: ConfigResponse) {
-  localStorage.setItem(LOCAL_STORAGE_KEY, JSON.stringify(translations));
-}
-
 export const getConfig = async (): Promise<ConfigResponse> => {
   const response = await fetchAPI(`config/`);
 
   if (!response.ok) {
-    throw new APIError('Failed to get the doc', await errorCauses(response));
+    throw new APIError('Failed to get the config', await errorCauses(response));
   }
 
   const config = response.json() as Promise<ConfigResponse>;
-  setCachedTranslation(await config);
 
   return config;
 };
 
-export const KEY_CONFIG = 'config';
+export const QKEY_CONFIG = 'config';
 
 export function useConfig() {
-  const cachedData = getCachedTranslation();
-  const oneHour = 1000 * 60 * 60;
-
   return useQuery<ConfigResponse, APIError, ConfigResponse>({
-    queryKey: [KEY_CONFIG],
+    queryKey: [QKEY_CONFIG],
     queryFn: () => getConfig(),
-    initialData: cachedData,
-    staleTime: oneHour,
-    initialDataUpdatedAt: Date.now() - oneHour, // Force initial data to be considered stale
+    staleTime: debug.enabled('no-cache') ? 0 : 1000 * 60 * 60, // 1 hour
   });
 }

src/frontend/apps/impress/src/features/auth/api/useAuthQuery.tsx

@@ -1,4 +1,5 @@
 import { UseQueryOptions, useQuery } from '@tanstack/react-query';
+import debug from 'debug';
 
 import { APIError, errorCauses, fetchAPI } from '@/api';
 
@@ -33,7 +34,7 @@ export function useAuthQuery(
   return useQuery<User, APIError, User>({
     queryKey: [KEY_AUTH],
     queryFn: getMe,
-    staleTime: 1000 * 60 * 15, // 15 minutes
+    staleTime: debug.enabled('no-cache') ? 0 : 1000 * 60 * 15, // 15 minutes
     ...queryConfig,
   });
 }

src/frontend/apps/impress/src/pages/_app.tsx

@@ -18,6 +18,28 @@ export default function App({ Component, pageProps }: AppPropsWithLayout) {
   const getLayout = Component.getLayout ?? ((page) => page);
   const { t } = useTranslation();
 
+  if (process.env.NODE_ENV === 'development') {
+    /**
+     *  Enable debug namespaces as needed
+     *
+     *  They can be enabled:
+     *
+     *    via DEBUG environment variable
+     *      DEBUG="features:language,no-cache,..."
+     *
+     *    via browser console
+     *      window.debug = "features:language,no-cache,...";
+     *
+     *    via Local storage
+     *      window.localStorage.debug = "features:language,no-cache,...";
+     *
+     *    via code (uses Local storage)
+     *      import debug from 'debug';
+     *      debug.enable('no-cache,features:language,...');
+     */
+    //debug.enable('no-cache,features:language');
+  }
+
   return (
     <>
       <Head>