🧑‍💻(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"
@@ -795,6 +802,16 @@ class Development(Base):
     CSRF_TRUSTED_ORIGINS = ["http://localhost:8072", "http://localhost:3000"]
     DEBUG = True
 
+    # Enable debug namespaces as needed
+    #
+    # They can also be enabled via DEBUG environment variable
+    #   DEBUG="features:language,no-cache,..."
+    #
+    # DEBUG_NAMESPACES = [
+    #     'no-cache',
+    #     'features:language'
+    # ]
+
     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

@@ -4,6 +4,7 @@ import { Resource } from 'i18next';
 import { APIError, errorCauses, fetchAPI } from '@/api';
 import { Theme } from '@/cunningham/';
 import { PostHogConf } from '@/services';
+import debug from 'debug';
 
 interface ThemeCustomization {
   translations?: Resource;
@@ -43,6 +44,6 @@ export function useConfig() {
   return useQuery<ConfigResponse, APIError, ConfigResponse>({
     queryKey: [QKEY_CONFIG],
     queryFn: () => getConfig(),
-    staleTime: 1000 * 60 * 60, // 1 hour
+    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>