Async Route feature with Callback and Server-Sent Events (SSE) support

[mdaneri]

This commit introduces the Async Route feature for Pode, including Callback and Server-Sent Events (SSE) support for improved asynchronous communication.

Benefits:

• Improved Responsiveness: Async Routes enable your Pode application to handle multiple requests concurrently, reducing response times and improving overall system responsiveness.

• Scalability: By creating independent runspace pools, you can efficiently manage resources and scale your application to handle increased loads or complex tasks.

• Enhanced Security: With Pode's security features integrated with Async Routes, you can ensure that only authorized users have access to sensitive information and operations.

• Flexible Task Management: Async Routes provide a unified interface for managing asynchronous tasks, allowing you to easily create, stop, query, or callback on running tasks.

New Features:

• Async Routes: Implemented the Async Route feature to handle asynchronous operations more efficiently.
• New Public Functions: Introduced new public functions in the Async.ps1 file to support the Async Route feature. These functions facilitate the creation, management, and execution of asynchronous tasks within Pode, providing developers with more flexibility and control over async operations.

New Functions:

• Add-PodeAsyncGetRoute: Creates a route to get the status and details of an asynchronous task, supporting different methods for task ID retrieval (Cookie, Header, Path, Query) and various response types (JSON, XML, YAML). Integrates with OpenAPI documentation.
• Add-PodeAsyncStopRoute: Adds a route to stop an asynchronous task, supporting task ID retrieval methods and response types. Integrates with OpenAPI documentation.
• Add-PodeAsyncQueryRoute: Adds a route for querying task information based on specified parameters. Supports multiple content types for both requests and responses and can generate OpenAPI documentation.
• Set-PodeAsyncRoute: Defines routes in Pode for asynchronous execution with runspace management, supporting response types (JSON, XML, YAML), callback functionality, and SSE. Each route creates an independent runspace pool, configurable with a minimum and maximum number of simultaneous runspaces.
• Get-PodeQueryAsyncRouteOperation: Acts as a public interface for searching asynchronous Pode route operations based on specified query conditions.
• Get-PodeAsyncRouteOperation: Fetches details of an asynchronous Pode route operation by its ID.
• Stop-PodeAsyncRouteOperation: Aborts a specific asynchronous Pode route operation by its ID, setting its state to 'Aborted' and disposing of the associated runspace.
• Test-PodeAsyncRouteOperation: Checks if a specific asynchronous Pode route operation exists by its ID, returning a boolean value.

Features

Independent Runspace Pools:

• Configurable Runspaces: Each async route creates an independent runspace pool that is configurable with a minimum and maximum number of simultaneous runspaces, allowing for efficient resource management and scalability.

Security:

• Pode Security: All async route operations are subject to Pode security, ensuring that any task operation complies with defined authentication and authorization rules.

Callback Support:

• Callback Functionality: Supports including callback functionality for routes, with options for URL, content type, HTTP method, and header fields. Callback support is integrated with OpenAPI definitions to provide detailed route information and response schemas.

SSE Support:

• SSE Support: Added Server-Sent Events support for real-time updates and seamless async communication.

Tests:

• Created a complex Pester test with merged authentication to ensure the robustness of the Async Route implementation. This test highlights potential challenges with PowerShell 5.x compatibility.
• Added a stress test script, Async-Computing.ps1, which evaluates the performance with 100 concurrent runspaces and over 250 parallel requests, ensuring the feature can handle high load scenarios.

Example Usage:

Add-PodeAsyncGetRoute:

Add-PodeAsyncGetRoute -Path '/task' -ResponseContentType  'application/json', 'application/yaml'  -In Path -Authentication 'MergedAuth' -Access 'MergedAccess' -Group 'Software' -TaskIdName 'myTaskId'

Add-PodeAsyncStopRoute:

Add-PodeAsyncStopRoute -Path '/task' -ResponseContentType 'application/json', 'application/yaml' -In Query -Authentication 'MergedAuth' -Access 'MergedAccess' -Group 'Software' -TaskIdName 'myTaskId''pippopppoId'

Add-PodeAsyncQueryRoute:

 Add-PodeAsyncQueryRoute -Path '/task' -ResponseContentType 'application/json', 'application/yaml' -In Query -Authentication 'MergedAuth' -Access 'MergedAccess' -Group 'Software' -TaskIdName 'myTaskId'

Set-PodeAsyncRoute:

Add-PodeRoute -PassThru -Method Put -Path '/auth/asyncUsing' -Authentication 'MergedAuth' -Access 'MergedAccess' -Group 'Software'   -ScriptBlock {
        return @{ InnerValue = 'something' }
    } | Set-PodeAsyncRoute -ResponseContentType 'application/json', 'application/yaml' -Callback -PassThru -CallbackSendResult -Timeout 300 | Set-PodeOARequest  -RequestBody (
        New-PodeOARequestBody -Content @{'application/json' = (New-PodeOAStringProperty -Name 'callbackUrl' -Format Uri -Object -Example 'http://localhost:8080/receive/callback') }
    )

Other functions:

• Get-PodeQueryAsyncRouteOperation:

• Get-PodeAsyncRouteOperation:

• Stop-PodeAsyncRouteOperation:

• Test-PodeAsyncRouteOperation:

Are the internal functions equivalent to route operations. The only difference is that there is no security involved. The main purpose of these functions are manipulate the internal state of the async routes.