feat: add templating utils method dynamically; method to set http code

Added new utils.set_http_response(integer) to set the HTML response
code from a template. Useful for error handling inside template.

Also noted that a real TemplatingUtils (like set_http_response) method
gets the TemplatingUtils object instance, but there is no way to do
this with registerUtil() from an extension file.

Added new instance.registerUtilMethod() method to register a function
in an extension as a method passing the client instance in as the first
parameter (aka self).

Author: rouilj

CHANGES.txt

@@ -95,7 +95,13 @@ Features:
 - issue2551116 - Replace xmlrpclib (xmlrpc.client) with defusedxml.
   Added support for defusedxml to better secure the xmlrpc
   endpoint. (John Rouillard)
-
+- Added new instance.registerUtilMethod() method to make using complex
+  templating easier as it provides a default Client instance to the
+  templating method. (John Rouillard)
+- Added new templating utils.set_http_response(integer) method to
+  allow reporting an error to the user from a template. (John
+  Rouillard)
+	
 2024-07-13 2.4.0
 
 Fixed:

doc/admin_guide.txt

@@ -443,6 +443,8 @@ when invoked.
 More secure CSPs can also be created. However because of the ability
 to customise the web interface, it is difficult to provide guidance.
 
+.. _dynamic_csp:
+
 Dynamic CSP
 -----------
 
@@ -469,7 +471,7 @@ directory that generates the CSP on the fly. For example::
     }
 
 
-    def AddHtmlHeaders(client, header_dict=None):
+    def AddHtmlHeaders(self, header_dict=None):
 	''' Generate https headers from dict use default security headers
 
 	    Setting the header with a value of None will not inject the
@@ -479,34 +481,35 @@ directory that generates the CSP on the fly. For example::
 	    nonce. Use to set a nonce for inline scripts.
 	'''
 	try:
-	    if client.client_nonce is None:
+	    if self.client.client_nonce is None:
 		# logger.warning("client_nonce is None")
-		client.client_nonce = client.session_api._gen_sid()
+		self.client.client_nonce = self.client.session_api._gen_sid()
 	except AttributeError:
-	    # client.client_nonce doesn't exist, create it
+	    # self.client.client_nonce doesn't exist, create it
 	    # logger.warning("client_nonce does not exist, creating")
-	    client.client_nonce = client.session_api._gen_sid()
+	    self.client.client_nonce = client.session_api._gen_sid()
 
 	headers = default_security_headers.copy()
 	if isinstance(header_dict, dict):
             headers.update(header_dict)
 
-	client_headers = client.additional_headers
+	client_headers = self.client.additional_headers
 
 	for header, value in list(headers.items()):
 	    if value is None:
 		continue
 	    client_headers[header] = value.format(
-                nonce=client.client_nonce)
+                nonce=self.client.client_nonce)
 
     def init(instance):
-        instance.registerUtil('AddHtmlHeaders', AddHtmlHeaders)
+        # Note the use of the new (in version 2.5) registerUtilMethod
+        instance.registerUtilMethod('AddHtmlHeaders', AddHtmlHeaders)
 
 
 Adding the following to ``page.html`` right after the opening
 ``<html....`>`` tag::
 
-   <tal:code tal:content="python:utils.AddHtmlHeaders(request.client)" />
+   <tal:code tal:content="python:utils.AddHtmlHeaders()" />
 
 will invoke ``AddHtmlHeaders()`` to add the CSP header with the nonce.
 
@@ -523,6 +526,43 @@ to::
 
 for each script, object or style tag.
 
+If you are using a version of Roundup before version 2.5, you need to
+replace ``instance.registerUtilMethod`` with
+``instance.registerUtil``. For example::
+
+    def init(instance):
+        # Note the use of the new (in version 2.5) registerUtilMethod
+        instance.registerUtil('AddHtmlHeaders', AddHtmlHeaders)
+
+The AddHtmlHeaders function needs to be changed so that ``self.client``
+is replaced by ``client``::
+
+    # replace self parameter with client
+    def AddHtmlHeaders(client, header_dict=None):
+	''' Generate https headers from dict use default security headers
+
+	    Setting the header with a value of None will not inject the
+	    header and can override the default set.
+
+	    Header values will be formatted with a dictionary including a
+	    nonce. Use to set a nonce for inline scripts.
+	'''
+
+	### Then change all references to self.client to client
+
+	try:
+	    if client.client_nonce is None:  # note self.client -> client
+		# logger.warning("client_nonce is None")
+		client.client_nonce = self.client.session_api._gen_sid()
+
+	...
+
+Lastly the client must be passed explicitly when calling
+AddHtmlHeaders. The call looks like::
+
+   <tal:code tal:content="python:utils.AddHtmlHeaders(request.client)" />
+
+
 Remediating ``unsafe-inline``
 -----------------------------
 .. _remediating unsafe-inline:

doc/reference.txt

@@ -1148,6 +1148,11 @@ mechanism.
   (see `adding a time log to your issues
   <customizing.html#adding-a-time-log-to-your-issues-4>`_ for an example)
 
+* ``instance.registerUtilMethod`` is also used for adding `templating
+  utilities`_, and provides a client instance by default to the
+  function. This makes more complex templating actions easier to
+  use. (see :ref:`dynamic_csp` for an example)
+
 * ``instance.registerAction`` is used to add more actions to the
   instance and to web interface. See `Defining new web actions`_
   for details.  Generic action can be added by inheriting from
@@ -3465,22 +3470,23 @@ be added to the variable by using extensions_.
 .. table::
   :class: valign-top
 
-  =============== ========================================================
-  Method          Description
-  =============== ========================================================
-  Batch           return a batch object using the supplied list
-  anti_csrf_nonce returns the random nonce generated for this session
-  expandfile      load a file into a template and expand
-                  '%(tokenname)s' in the file using
-                  values from the supplied dictionary.
-  html_quote      quote some text as safe in HTML (ie. <, >, ...)
-  html_calendar   renders an HTML calendar used by the
-		  ``_generic.calendar.html`` template (itself invoked by
-		  the popupCalendar DateHTMLProperty method
-  readfile        read JavaScript or other content in an external
-                  file into the template.
-  url_quote       quote some text as safe for a URL (ie. space, %, ...)
-  =============== ========================================================
+  ================= ========================================================
+  Method            Description
+  ================= ========================================================
+  Batch             return a batch object using the supplied list
+  anti_csrf_nonce   returns the random nonce generated for this session
+  expandfile        load a file into a template and expand
+                    '%(tokenname)s' in the file using
+                    values from the supplied dictionary.
+  html_quote        quote some text as safe in HTML (ie. <, >, ...)
+  html_calendar     renders an HTML calendar used by the
+		    ``_generic.calendar.html`` template (itself invoked by
+		    the popupCalendar DateHTMLProperty method
+  readfile          read JavaScript or other content in an external
+                    file into the template.
+  set_http_response sets the HTTP response code for the request.
+  url_quote         quote some text as safe for a URL (ie. space, %, ...)
+  ================= ========================================================
 
 Additional info can be obtained by starting ``python`` with the
 ``roundup`` subdirectory on your PYTHONPATH and using the Python help

doc/upgrading.txt

@@ -253,6 +253,28 @@ occurs before any database changes are made. Now, all errors related
 to the data format (mime type, API version) will return 406 errors,
 where some previously resulted in 400 errors.
 
+New method for registering templating utils (info)
+--------------------------------------------------
+
+If you are building a template utility function that needs access
+to:
+
+  * the database
+  * the client instance
+  * the form the user submitted
+
+you had to pass these objects from the template using the ``db``,
+``request.client`` or ``request.form``  arguments.
+
+A new method for registering a template utility has been
+added. If you use the ``instance`` object's
+``registerUtilMethod()`` to register a utility function, you do
+not need to pass these arguments. The function is called as a
+method and the first argument is a ``client`` instance from which
+the database (client.db), form (client.form).
+
+You can find an example in :ref:`dynamic_csp`.
+
 .. index:: Upgrading; 2.3.0 to 2.4.0
 
 Migrating from 2.3.0 to 2.4.0

roundup/cgi/templating.py

@@ -3799,6 +3799,18 @@ def expandfile(self, name, values=None, optional=False):
                 {'fullpath': fullpath, 'issue': e.args[0]})
             return ""
 
+    def set_http_response(self, code):
+        '''Set the HTTP response code to the integer `code`.
+            Example::
+
+              <tal:x
+               tal:replace="python:utils.set_response(404);"
+              />
+
+
+            will make the template return code 404 (not found).
+            '''
+        self.client.response_code = code
 
 class MissingValue(object):
     def __init__(self, description, **kwargs):

roundup/instance.py

@@ -247,8 +247,38 @@ def registerAction(self, name, action):
             self.cgi_actions[name] = action
 
     def registerUtil(self, name, function):
+        """Register a function that can be called using:
+           `utils.<name>(...)`.
+
+           The function is defined as:
+
+               def function(...):
+
+           If you need access to the client, database, form or other
+           item, you have to pass it explicitly::
+
+               utils.name(request.client, ...)
+
+           If you need client access, consider using registerUtilMethod()
+           instead.
+
+        """
         self.templating_utils[name] = function
 
+    def registerUtilMethod(self, name, function):
+        """Register a method that can be called using:
+           `utils.<name>(...)`.
+
+           Unlike registerUtil, the method is defined as:
+
+               def function(self, ...):
+
+           `self` is a TemplatingUtils object. You can use self.client
+           to access the client object for your request.
+        """
+        setattr(self.TemplatingUtils,
+                name, 
+                function)
 
 class TrackerError(RoundupException):
     pass