From 85ed12c69491bbba25642d4cc25c0c44c39d155e Mon Sep 17 00:00:00 2001
From: dbauszus-glx <dennis.bauszus@geolytix.co.uk>
Date: Wed, 30 Oct 2024 12:47:13 +0000
Subject: [PATCH] Explain the WORKSPACE AGE in more detail

---
 mod/workspace/_workspace.js  | 2 ++
 mod/workspace/cache.js       | 5 ++++-
 mod/workspace/getTemplate.js | 2 +-
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/mod/workspace/_workspace.js b/mod/workspace/_workspace.js
index 9b77efa480..b7d2a04ad4 100644
--- a/mod/workspace/_workspace.js
+++ b/mod/workspace/_workspace.js
@@ -284,6 +284,8 @@ function roles(req, res) {
 @description
 The workspace/test method which is only available to user with admin credentials requests all locales in workspace.
 
+The cached workspace will be flushed for the test method.
+
 Requesting all locales should add any additional templates to the workspace.
 
 The test method will iterate over all workspace.templates and get from the getTemplate method to check whether any errors are logged on a template in regards to its src parameter.
diff --git a/mod/workspace/cache.js b/mod/workspace/cache.js
index 365a54d9f4..132ddeee0d 100644
--- a/mod/workspace/cache.js
+++ b/mod/workspace/cache.js
@@ -14,6 +14,7 @@ const getFrom = require('../provider/getFrom')
 
 const merge = require('../utils/merge')
 
+// Assign default age in ms.
 process.env.WORKSPACE_AGE ??= 3600000
 
 let cache = null
@@ -28,7 +29,9 @@ const logger = require('../utils/logger')
 @description
 The method checks whether the module scope variable cache has been populated.
 
-The age of the cached timestamp is checked against the WORKSPACE_AGE environment variable.
+The timestamp set by cacheWorkspace is checked against the current time. The [workspace] cache will be invalidated if the difference exceeds the WORKSPACE_AGE environment variable.
+
+Setting the WORKSPACE_AGE to 0 is not recommended as this could cause the cache to be flushed while a request is passed through the XYZ API. A layer query processed by the [Query API module]{@link module:/query~layerQuery} will request the layer and associated locale which could be defined in remote templates. Each request to the [Workspace API getTemplate]{@link module:/workspace/getTemplate~getTemplate} method for the locale, layer, and query templates will call the checkWorkspaceCache method which will cause the workspace to be flushed and templates previously cached from their src no longer available.
 
 The cacheWorkspace method is called if the cache is invalid.
 
diff --git a/mod/workspace/getTemplate.js b/mod/workspace/getTemplate.js
index 58c3d86c8b..8eb02aeeb4 100644
--- a/mod/workspace/getTemplate.js
+++ b/mod/workspace/getTemplate.js
@@ -33,7 +33,7 @@ const envReplace = require('../utils/envReplace')
 @async
 
 @description
-The workspace will be requested from the workspace/cache module.
+The workspace will checked and cached by the [Workspace API checkWorkspaceCache]{@link module:/workspace/cache~checkWorkspaceCache} method.
 
 A template object matching the template_key param in the workspace.templates{} object will be returned from the getTemplate method.