Adddons: allow injecting an "always live" JavaScript file

We talked about giving users a way to inject a JavaScript file they control
using our Cloudflare Worker infrastructure to allow them manipulate frozen
documentations.

This could be used in different ways to fix bugs or add features to a particular
frozen set of docs or even to all the versions. The user can make usage of API
data to filter by version or not
(e.g. `if (versions.current == "v3.0") { .. do something ...} `)

The script could live in Read the Docs itself using a relative URL, or outside
it, using an absolute URL.

Author: humitos

dockerfiles/nginx/proxito.conf.template

@@ -125,6 +125,8 @@ server {
         add_header X-RTD-Hosting-Integrations $rtd_hosting_integrations always;
         set $rtd_force_addons $upstream_http_x_rtd_force_addons;
         add_header X-RTD-Force-Addons $rtd_force_addons always;
+        set $rtd_user_js_file $upstream_http_x_rtd_user_js_file;
+        add_header X-RTD-User-Js-File $rtd_user_js_file always;
     }
 
     # Serve 404 pages here

readthedocs/projects/migrations/0132_addons_user_js_file.py

@@ -0,0 +1,25 @@
+# Generated by Django 4.2.16 on 2024-11-11 17:05
+
+from django.db import migrations, models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy
+
+    dependencies = [
+        ('projects', '0131_increase_env_var_size'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='addonsconfig',
+            name='js_file',
+            field=models.CharField(blank=True, help_text='URL to a JavaScript file to inject at serve time', max_length=512, null=True),
+        ),
+        migrations.AddField(
+            model_name='historicaladdonsconfig',
+            name='js_file',
+            field=models.CharField(blank=True, help_text='URL to a JavaScript file to inject at serve time', max_length=512, null=True),
+        ),
+    ]

readthedocs/projects/models.py

@@ -162,6 +162,15 @@ class AddonsConfig(TimeStampedModel):
         help_text="Enable/Disable all the addons on this project",
     )
 
+    # This is a user-defined file that will be injected at serve time by our
+    # Cloudflare Worker if defined
+    js_file = models.CharField(
+        max_length=512,
+        null=True,
+        blank=True,
+        help_text="URL to a JavaScript file to inject at serve time",
+    )
+
     # Analytics
 
     # NOTE: we keep analytics disabled by default to save resources.

readthedocs/proxito/middleware.py

@@ -34,7 +34,7 @@
     unresolver,
 )
 from readthedocs.core.utils import get_cache_tag
-from readthedocs.projects.models import Feature, Project
+from readthedocs.projects.models import AddonsConfig, Feature, Project
 from readthedocs.proxito.cache import add_cache_tags, cache_response, private_response
 from readthedocs.proxito.redirects import redirect_to_https
 
@@ -303,13 +303,16 @@ def add_hosting_integrations_headers(self, request, response):
                 tzinfo=tzinfo,
             )
             if addons_enabled_by_default:
-                addons = Project.objects.filter(
-                    slug=project_slug, addons__enabled=True
-                ).exists()
+                addons = AddonsConfig.objects.filter(project__slug=project_slug).first()
+                if not addons:
+                    return
 
-                if addons:
+                if addons.enabled:
                     response["X-RTD-Force-Addons"] = "true"
-                    return
+
+                if addons.js_file:
+                    # response["X-RTD-User-Js-File"] = "/en/full-feature/readthedocs.js"
+                    response["X-RTD-User-Js-File"] = addons.js_file
 
             else:
                 # TODO: remove "else" code once DISABLE_SPHINX_MANIPULATION and addons becomes the default