feat: Add custom placeholder pages for scale-from-zero scenarios

[malpou]

Allows HTTPScaledObjects to serve configurable HTML pages while workloads scale up from zero, with support for templates,
custom headers, and automatic refresh.

Description

This PR implements customizable placeholder pages that are displayed to users while applications are scaling up from zero.
This significantly improves the user experience during cold starts by providing immediate feedback instead of connection
timeouts or errors.

Key features:

• Adds placeholderConfig section to HTTPScaledObject CRD for configuring placeholder pages
• Supports both inline HTML content and ConfigMap-based templates
• Includes Go template support with variables like {{.ServiceName}} and {{.RefreshInterval}}
• Automatic page refresh capability to check when the service becomes available
• Custom HTTP headers and status codes
• Configurable timeout for how long to show placeholder pages

Implementation details:

• New placeholder handler in the interceptor that serves configured HTML when backends are unavailable
• Graceful fallback to upstream requests once the service is ready
• Full backward compatibility - disabled by default

Checklist

• Commits are signed with Developer Certificate of Origin (DCO)
• Changelog has been updated and is aligned with our changelog requirements
• Any necessary documentation is added, such as:
  • README.md
  • The docs/ directory
  • The docs repo

Fixes #874

[JorTurFer]

This is a great feature! Thanks for the contribution 🙇

[JorTurFer]

Should we inject this value instead of expect that users provide it? I mean, this looks as something that we want to enforce. @wozniakjan ?

[malpou]

I was thinking about injecting it but wanted some feedback first.

I think it also would be possible to add some JavaScript instead which calls the URL the browser is on and checks if the X-KEDA-HTTP-Placeholder-Served: true header is there. If it's not we should do a full refresh.
This avoids having the browser do an actual refresh every X seconds. This would mostly be an UX improvement.

Both approaches could be injected into whatever template the user provides, if that's the approach you would prefer.

Example:

<script>
(function() {
    const checkInterval = {{.RefreshInterval}} * 1000; // Convert seconds to milliseconds
    
    async function checkServiceStatus() {
        try {
            // Make a HEAD request to the current URL to check headers
            const response = await fetch(window.location.href, {
                method: 'HEAD',
                cache: 'no-cache'
            });
            
            // Check if the placeholder header is present
            const placeholderHeader = response.headers.get('X-KEDA-HTTP-Placeholder-Served');
            
            if (placeholderHeader !== 'true') {
                // Service is ready! Do a full page refresh
                window.location.reload();
            } else {
                // Still showing placeholder, check again later
                setTimeout(checkServiceStatus, checkInterval);
            }
        } catch (error) {
            // On error, continue checking
            console.error('Error checking service status:', error);
            setTimeout(checkServiceStatus, checkInterval);
        }
    }
    
    // Start checking after the interval
    setTimeout(checkServiceStatus, checkInterval);
})();
</script>

[JorTurFer]

I like this approach! it's quite elegant IMHO, the only thing is that JS needs to be injected as well, doesn't

[JorTurFer]

@wozniakjan @zroubalik WDYT?

[malpou]

@JorTurFer I've tried to make a take on the injection with a <script> tag and some JS to figure out when to refresh the browser.

[Copilot]

Pull Request Overview

This PR introduces configurable placeholder pages for scale-from-zero scenarios, enhancing the user experience during cold starts. Key changes include:

• Adding a new placeholder handler and supporting API changes in the HTTPScaledObject CRD.
• Adjusting proxy handler logic and test cases to incorporate placeholder page responses.
• Updating documentation, examples, and deepcopy functions to reflect the new placeholderConfig functionality.

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/checks/placeholder_pages/placeholder_pages_test.go	Added E2E tests for placeholder page responses and script injection.
operator/apis/http/v1alpha1/zz_generated.deepcopy.go	Added DeepCopy functions for the new PlaceholderConfig type.
operator/apis/http/v1alpha1/httpscaledobject_types.go	Introduced the PlaceholderConfig type in the CRD schema.
interceptor/proxy_handlers_test.go, proxy_handlers_integration_test.go	Updated tests to pass new parameters for placeholder handling.
interceptor/proxy_handlers.go	Integrated the placeholder handler into the forwarding logic.
interceptor/main.go, main_test.go	Updated server initialization to include the placeholder handler.
interceptor/handler/placeholder.go	Implemented the placeholder page rendering and caching logic.
examples/vX.X.X/httpscaledobject.yaml	Provided example configuration for placeholder pages.
docs/ref/vX.X.X/http_scaled_object.md	Documented the placeholderConfig section details.
config/crd/bases/http.keda.sh_httpscaledobjects.yaml	Updated the CRD with placeholderConfig properties.
CHANGELOG.md	Added an entry for the custom placeholder pages feature.

Comments suppressed due to low confidence (1)

interceptor/handler/placeholder.go:206

• [nitpick] Consider logging the error returned from getTemplate before falling back to the inline response to improve debuggability of template parsing issues.

tmpl, err := h.getTemplate(r.Context(), hso)

[Copilot]

[nitpick] Consider checking if the placeholder script is already present in the template content before injecting it to avoid potential duplicate script insertions.

Suggested change

	func injectPlaceholderScript(templateContent string) string {
	func injectPlaceholderScript(templateContent string) string {
	// Check if the placeholder script is already present
	if strings.Contains(templateContent, placeholderScript) {
	// Return the original content if the script is already present
	return templateContent
	}

[JorTurFer]

awesome job! Only one small nit inline and it's okey to merge ❤️

[JorTurFer]

In case of high pressure, I'd say that more than 1 placeholder can be init. WDYT about something like?

Suggested change

	h.cacheMutex.RUnlock()
	injectedContent := injectPlaceholderScript(config.Content)
	tmpl, err := template.New("inline").Parse(injectedContent)
	if err != nil {
	return nil, err
	}
	h.cacheMutex.Lock()
	h.cacheMutex.RUnlock()
	h.cacheMutex.Lock()
	injectedContent := injectPlaceholderScript(config.Content)
	tmpl, err := template.New("inline").Parse(injectedContent)
	if err != nil {
	return nil, err
	}

[JorTurFer]

same as above