Proxito: allow to generate proxied API URLs with a prefix

- Ref #10181
- Ref #10408
- Ref readthedocs/meta#124

Author: stsewd

readthedocs/api/v2/serializers.py

@@ -31,6 +31,7 @@ class Meta:
             'users',
             'canonical_url',
             'urlconf',
+            'custom_prefix',
         )
 
 

readthedocs/projects/models.py

@@ -693,11 +693,9 @@ def proxied_api_host(self):
         This needs to start with a slash at the root of the domain,
         and end without a slash
         """
-        if self.urlconf:
-            # Add our proxied api host at the first place we have a $variable
-            # This supports both subpaths & normal root hosting
-            path_prefix = self.custom_path_prefix
-            return unsafe_join_url_path(path_prefix, "/_")
+        custom_prefix = self.proxied_api_prefix
+        if custom_prefix:
+            return unsafe_join_url_path(custom_prefix, "/_")
         return '/_'
 
     @property
@@ -715,12 +713,20 @@ def proxied_static_path(self):
         return f"{self.proxied_api_host}/static/"
 
     @property
-    def custom_path_prefix(self):
+    def proxied_api_prefix(self):
         """
-        Get the path prefix from the custom urlconf.
+        Get the path prefix for proxied API paths (``/_/``).
 
         Returns `None` if the project doesn't have a custom urlconf.
         """
+        # When using a custom prefix, we can only handle serving
+        # docs pages under the prefix, not special paths like `/_/`.
+        # Projects using the old implementation, need to proxy `/_/`
+        # paths as is, this is, without the suffix, while those projects
+        # migrate to the new implementation, we will prefix special paths,
+        # they are manually un-prefixed in nginx.
+        if self.custom_prefix and self.has_feature(Feature.USE_PROXIED_APIS_WITH_PREFIX):
+            return self.custom_prefix
         if self.urlconf:
             # Return the value before the first defined variable,
             # as that is a prefix and not part of our normal doc patterns.
@@ -1930,6 +1936,7 @@ def add_features(sender, **kwargs):
     DISABLE_PAGEVIEWS = "disable_pageviews"
     RESOLVE_PROJECT_FROM_HEADER = "resolve_project_from_header"
     USE_UNRESOLVER_WITH_PROXITO = "use_unresolver_with_proxito"
+    USE_PROXIED_APIS_WITH_PREFIX = "use_proxied_apis_with_prefix"
     ALLOW_VERSION_WARNING_BANNER = "allow_version_warning_banner"
 
     # Versions sync related features
@@ -2020,6 +2027,12 @@ def add_features(sender, **kwargs):
                 "Proxito: Use new unresolver implementation for serving documentation files."
             ),
         ),
+        (
+            USE_PROXIED_APIS_WITH_PREFIX,
+            _(
+                "Proxito: Use proxied APIs (/_/*) with the custom prefix if the project has one (Project.custom_prefix)."
+            ),
+        ),
         (
             ALLOW_VERSION_WARNING_BANNER,
             _("Dashboard: Allow project to use the version warning banner."),