Magic parameters for canned queries

Closes #842

Includes a new plugin hook, register_magic_parameters()

docs/plugin_hooks.rst

@@ -895,3 +895,42 @@ Here's an example that allows users to view the ``admin_log`` table only if thei
 See :ref:`built-in permissions <permissions>` for a full list of permissions that are included in Datasette core.
 
 Example: `datasette-permissions-sql <https://github.com/simonw/datasette-permissions-sql>`_
+
+.. _plugin_hook_register_magic_parameters:
+
+register_magic_parameters(datasette)
+------------------------------------
+
+``datasette`` - :ref:`internals_datasette`
+    You can use this to access plugin configuration options via ``datasette.plugin_config(your_plugin_name)``.
+
+:ref:`canned_queries_magic_parameters` can be used to add automatic parameters to :ref:`canned queries <canned_queries>`. This plugin hook allows additional magic parameters to be defined by plugins.
+
+Magic parameters all take this format: ``_prefix_rest_of_parameter``. The prefix indicates which magic parameter function should be called - the rest of the parameter is passed as an argument to that function.
+
+To register a new function, return it as a tuple of ``(string prefix, function)`` from this hook. The function you register should take two arguments: ``key`` and ``request``, where ``key`` is the ``rest_of_parameter`` portion of the parameter and ``request`` is the current :ref:`internals_request`.
+
+This example registers two new magic parameters: ``:_request_http_version`` returning the HTTP version of the current request, and ``:_uuid_new`` which returns a new UUID:
+
+.. code-block:: python
+
+    from uuid import uuid4
+
+    def uuid(key, request):
+        if key == "new":
+            return str(uuid4())
+        else:
+            raise KeyError
+
+    def request(key, request):
+        if key == "http_version":
+            return request.scope["http_version"]
+        else:
+            raise KeyError
+
+    @hookimpl
+    def register_magic_parameters(datasette):
+        return [
+            ("request", request),
+            ("uuid", uuid),
+        ]

docs/sql_queries.rst

@@ -114,8 +114,8 @@ rendered as HTML (rather than having HTML special characters escaped).
 
 .. _canned_queries_named_parameters:
 
-Named parameters
-~~~~~~~~~~~~~~~~
+Canned query parameters
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Canned queries support named parameters, so if you include those in the SQL you
 will then be able to enter them using the form fields on the canned query page
@@ -274,6 +274,58 @@ You can use ``"params"`` to explicitly list the named parameters that should be
 
 You can pre-populate form fields when the page first loads using a querystring, e.g. ``/mydatabase/add_name?name=Prepopulated``. The user will have to submit the form to execute the query.
 
+.. _canned_queries_magic_parameters:
+
+Magic parameters
+~~~~~~~~~~~~~~~~
+
+Named parameters that start with an underscore are special: they can be used to automatically add values created by Datasette that are not contained in the incoming form fields or querystring.
+
+Available magic parameters are:
+
+``_actor_*`` - e.g. ``_actor_id``, ``_actor_name``
+    Fields from the currently authenticated :ref:`authentication_actor`.
+
+``_header_*`` - e.g. ``_header_user_agent``
+    Header from the incoming HTTP request. The key should be in lower case and with hyphens converted to underscores e.g. ``_header_user_agent`` or ``_header_accept_language``.
+
+``_cookie_*`` - e.g. ``_cookie_lang``
+    The value of the incoming cookie of that name.
+
+``_timestamp_epoch``
+    The number of seconds since the Unix epoch.
+
+``_timestamp_date_utc``
+    The date in UTC, e.g. ``2020-06-01``
+
+``_timestamp_datetime_utc``
+    The ISO 8601 datetime in UTC, e.g. ``2020-06-24T18:01:07Z``
+
+``_random_chars_*`` - e.g. ``_random_chars_128``
+    A random string of characters of the specified length.
+
+Here's an example configuration (this time using ``metadata.yaml`` since that provides better support for multi-line SQL queries) that adds a message from the authenticated user, storing various pieces of additional metadata using magic parameters:
+
+.. code-block:: yaml
+
+    databases:
+      mydatabase:
+        queries:
+          add_message:
+            allow:
+              id: "*"
+            sql: |-
+              INSERT INTO messages (
+                user_id, ip, message, datetime
+              ) VALUES (
+                :_actor_id, :_request_ip, :message, :_timestamp_datetime_utc
+              )
+            write: true
+
+The form presented at ``/mydatabase/add_message`` will have just a field for ``message`` - the other parameters will be populated by the magic parameter mechanism.
+
+Additional custom magic parameters can be added by plugins using the :ref:`plugin_hook_register_magic_parameters` hook.
+
 .. _pagination:
 
 Pagination