Add queue mode section and adaptive concurrency docs

[welteki]

Description

Reorganised the queue-worker docs to give queue mode its own section. Previously the static vs function mode distinction was only covered under queue-depth scaling, but it now unlocks multiple queue-worker features including queue-based scaling and adaptive concurrency.

Added a new adaptive concurrency section covering the problem it solves, how it works at a high level, and how to disable it.

Moved the async use-cases and blog references from the queue-worker page to the async reference page where they are more relevant. This keeps the queue-worker page focused on queue-worker configuration rather than general async use-cases.

Motivation and Context

The adaptive concurrency feature is new and needs to be documented. The queue mode and async reference pages were also updated to better organise the existing content.

• I have raised an issue to propose this change (required)

How Has This Been Tested?

Ran the docs site locally with docker to verify correct formatting and rendering.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I've read the CONTRIBUTION guide
• I have signed-off my commits with git commit -s

[reviewfn]

AI Pull Request Overview

Summary

• Reorganizes queue-worker documentation in jetstream.md by introducing a dedicated "Queue mode" section explaining static vs function modes.
• Adds new "Adaptive concurrency" section with detailed explanation, examples, and configuration.
• Moves async use-cases and blog references from jetstream.md to async.md for better organization.
• Updates references to retries and autoscaling in both files.
• Maintains focus on queue-worker configuration in jetstream.md while enhancing async reference.
• Tested locally with Docker to ensure proper formatting and rendering.
• No breaking changes to functionality, only documentation improvements.

Approval rating (1-10)

9 - Well-structured reorganization with clear new feature documentation, but minor link consistency issues.

Summary per file

Summary per file

File path	Summary
docs/openfaas-pro/jetstream.md	Added queue mode and adaptive concurrency sections, removed async use-cases content.
docs/reference/async.md	Added moved async use-cases and blog references, updated retries reference.

Do not include node_modules or vendor directories.

Overall Assessment

This PR effectively reorganizes and enhances the OpenFaaS documentation by introducing clear sections for new queue-worker features while improving content organization. The changes provide comprehensive coverage of adaptive concurrency and queue mode functionality, which are valuable additions for enterprise users. The reorganization maintains logical flow and improves discoverability of features. Minor concerns around potential broken links from moved content and consistency in configuration examples warrant attention before merge.

Detailed Review

Detailed Review

docs/openfaas-pro/jetstream.md

• Queue Mode Section: The new "Queue mode" section effectively explains the distinction between static and function modes. The YAML configuration examples are clear and well-formatted. The inactiveThreshold parameter is appropriately documented with a code example. However, consider adding a migration note for existing users upgrading from static to function mode, including any potential downtime or configuration validation steps.

• Adaptive Concurrency Section: This new section provides excellent coverage of the feature's purpose, mechanism, and configuration. The example with the sleep function is particularly helpful for understanding real-world application. The explanation of how it handles 429 responses and adjusts concurrency is technically accurate. Consider adding metrics or monitoring guidance for observing adaptive concurrency behavior in production.

• Queue-based Scaling: The rewrite clarifies that this requires function mode, which is good. The link to /reference/autoscaling/ should be verified to ensure it points to the correct section on queue-depth scaling.

• Content Removal: Removing async use-cases from this page improves focus on queue-worker specifics. The moved content to async.md is appropriate.

• Consistency: The YAML examples use consistent formatting. However, the adaptiveConcurrency: false example could benefit from showing it within the full jetstreamQueueWorker block for clarity.

• Potential Risks: Function mode creates dedicated consumers per function, which could impact NATS resource usage at scale. Consider adding guidance on monitoring NATS consumer counts and potential limits.

docs/reference/async.md

• Added Content: The moved async use-cases and blog references fit well in this reference page. The content enhances the async invocation documentation without disrupting flow.

• Retries Reference: Updating the retries bullet to point to /openfaas-pro/retries is appropriate, but verify this link exists and is accurate.

• Overall: The additions strengthen this as a comprehensive async reference. No major issues detected.

General Concerns

• Link Validation: All internal links (e.g., /reference/async, /reference/autoscaling/, /openfaas-pro/retries) should be tested to ensure they resolve correctly in the built documentation.

• Enterprise Features: The documentation correctly marks function mode and adaptive concurrency as enterprise features. Ensure pricing links are current.

• Testing: While local testing with Docker is mentioned, consider adding a note about testing links in the built site to catch any broken references.

• Backward Compatibility: The reorganization may break bookmarks or direct links to sections that moved. Consider adding redirects or update notices if this documentation has external users.

• Security/Performance: As documentation, no direct security concerns. The features documented (adaptive concurrency) aim to improve performance by preventing unnecessary retries, which is positive.

• Consistency with Codebase: The YAML configurations match typical OpenFaaS patterns. No issues with using strings for modes instead of constants, as this is configuration.

Recommendations

1. High priority: Verify all internal links in the updated documentation.
2. Medium priority: Add brief migration guidance for users enabling function mode.
3. Low priority: Consider adding monitoring recommendations for NATS consumers when using function mode.

AI agent details.

Agent processing time: 31.331s
Environment preparation time: 6.05s
Total time from webhook: 41.841s