Enhance Pode Server with Suspend, Resume, and Advanced Console Features #1461

mdaneri · 2024-12-08T17:32:43Z

Description

This pull request introduces the Suspend and Resume functionality for Pode, enabling the server to temporarily pause and later resume all activities without requiring a full restart. It also enhances the server's console output and interactivity, providing a more robust and user-friendly experience. Furthermore, server configurations (server.psd1) now support advanced console settings and control over allowed actions. New parameters have been added to the Start-PodeServer function, including -IgnoreServerPsConfig, enabling users to bypass loading configuration data from server.psd1.

Additionally, this pull request introduces the Disable-PodeServer and Enable-PodeServer functions, allowing for granular control over the server’s ability to accept incoming requests without impacting its overall state.

Key Features

Suspend-PodeServer:
- Temporarily pauses all server operations, including associated runspaces.
- Triggers a Suspend event and updates the server status.
- Includes an optional -Timeout parameter to specify the maximum wait time for runspaces to suspend.
Resume-PodeServer:
- Resumes server activities and restores all runspaces to their normal state.
- Triggers a Resume event, clears the server's suspended status, and updates the console view.
Disable-PodeServer:
- Temporarily blocks all new incoming requests to the Pode server while maintaining its active state.
- Responds to incoming requests with a 503 Service Unavailable status.
- Includes a Retry-After header, specifying the time (in seconds) clients should wait before retrying. The default value is 3600 seconds (1 hour).
- Example:
```
# Disable the Pode server with the default retry time
Disable-PodeServer

# Disable the Pode server with a custom retry time of 5 minutes
Disable-PodeServer -RetryAfter 300
```
Enable-PodeServer:
- Re-enables the Pode server to accept new incoming requests after being disabled.
- Resets the server's cancellation token for the disable action, allowing normal request handling to resume.
- Example:
```
# Re-enable the Pode server
Enable-PodeServer
```
Improved Console Output:
- Adds multiple interactive features for better server control:
  - Ctrl+C: Gracefully terminate the server.
  - Ctrl+R: Restart the server and reload configurations.
  - Ctrl+P: Suspend the server.
  - Ctrl+D: Disable new incoming requests (Disable-PodeServer).
  - Ctrl+B: Open the first HTTP endpoint in the default browser.
  - Ctrl+M: Display the server metrics.
  - Ctrl+H: Hide this help.
  - Ctrl+E: Hide Endpoints.
  - Ctrl+O: Hide OpenAPI details.
  - Ctrl+L: Clear the console.
  - Ctrl+Q: Enable Quiet Mode.
Endpoint and Schedule Initialization:
- Endpoints will no longer receive input, and schedules are not executed until the server is fully initialized, avoiding potential unstable states.

New Console Settings in server.psd1:

Introduced support for detailed console customization in the server configuration file:

@{
    Server = @{
        Console = @{
             DisableTermination  = $false    # Prevent Ctrl+C from terminating the server.
                 DisableConsoleInput = $false    # Disable all console input controls.
                 Quiet               = $false    # Suppress console output.
                 ClearHost           = $false    # Clear the console output at startup.
                 ShowOpenAPI         = $true     # Display OpenAPI information.
                 ShowEndpoints       = $true     # Display listening endpoints.
                 ShowHelp            = $false    # Show help instructions in the console.
                 ShowDivider         = $true     # Display dividers between sections.
                 DividerLength       = 75        # Length of dividers in the console.
                 ShowTimeStamp       = $true     # Display timestamp in the header.
     
                 Colors              = @{            # Customize console colors.
                     Header           = 'White'      # The server's header section, including the Pode version and timestamp.
                     EndpointsHeader  = 'Yellow'     # The header for the endpoints list.
                     Endpoints        = 'Cyan'       # The endpoints themselves, including protocol and URLs.
                     OpenApiUrls      = 'Cyan'       # URLs listed under the OpenAPI information section.
                     OpenApiHeaders   = 'Yellow'     # Section headers for OpenAPI information.
                     OpenApiTitles    = 'White'      # The OpenAPI "default" title.
                     OpenApiSubtitles = 'Yellow'     # Subtitles under OpenAPI (e.g., Specification, Documentation).
                     HelpHeader       = 'Yellow'     # Header for the Help section.
                     HelpKey          = 'Green'      # Key bindings listed in the Help section (e.g., Ctrl+c).
                     HelpDescription  = 'White'      # Descriptions for each Help section key binding.
                     HelpDivider      = 'Gray'       # Dividers used in the Help section.
                     Divider          = 'DarkGray'   # Dividers between console sections.
                     MetricsHeader    = 'Yellow'     # Header for the Metric section.
                     MetricsLabel     = 'White'      # Labels for values displayed in the Metrics section.
                     MetricsValue     = 'Green'      # The actual values displayed in the Metrics section.
                 }
     
                 KeyBindings         = @{        # Define custom key bindings for controls.
                     Browser   = 'B'             # Open the default browser.
                     Help      = 'H'             # Show/hide help instructions.
                     OpenAPI   = 'O'             # Show/hide OpenAPI information.
                     Endpoints = 'E'             # Show/hide endpoints.
                     Clear     = 'L'             # Clear the console output.
                     Quiet     = 'Q'             # Toggle quiet mode.
                     Terminate = 'C'             # Terminate the server.
                     Restart   = 'R'             # Restart the server.
                     Disable   = 'D'             # Disable the server.
                     Suspend   = 'P'             # Suspend the server.
                     Metrics   = 'M'             # Show Metrics.
                 }
            }
        }
    }
}

Allowed Actions Settings:

Added a new section in server.psd1 to control server behaviors, including timeouts for suspend and resume operations:

@{
    Server = @{
        AllowedActions = @{
           Suspend = $true        # Enable or disable the suspend operation
           Restart = $true          # Enable or disable the restart operation
           Disable = $true         # Enable or disable the disable operation
           DisableSettings = @{
               RetryAfter = 3600                               # Default retry time (in seconds) for Disable-PodeServer
               MiddlewareName = '__Pode_Midleware_Code_503'    # Name of the middleware scriptblock
           }
           Timeout = @{
               Suspend = 30       # Maximum seconds to wait before suspending
               Resume  = 30       # Maximum seconds to wait before resuming
           }
    }
}

New Console Settings for Start-PodeServer:
- New parameters to customize the console behavior:
  - -DisableConsoleInput: Disables keyboard interaction.
  - -ClearHost: Clears the console screen whenever the server changes state (e.g., running → suspend → resume).
  - -HideOpenAPI: Hides OpenAPI details in the console output.
  - -HideEndpoints: Hides the endpoint list in the console output.
  - -ShowHelp: Displays control commands in the console.
  - -IgnoreServerConfig: Ignores the server.psd1 configuration file when starting the server. This ensures that no settings defined in the server.psd1 file are loaded, allowing for manual runtime configuration.
  - -ConfigFile: Specifies a custom configuration file instead of using the default server.psd1.
  - -Daemon: Configures the server to run as a daemon with minimal console interaction and output.

Use Cases

Maintenance: Suspend or disable server activities for quick maintenance without a restart.
Traffic Management: Use Disable-PodeServer to block new incoming requests during high traffic and re-enable using Enable-PodeServer.
Custom Console Behavior: Enhance the server console with customizable settings and interactive features.
Fine-Grained Control: Use server.psd1 to define allowed actions and timeouts for suspend/resume transitions.

Example Usage

Start a server with custom console behavior:

Start-PodeServer -ClearHost -HideEndpoints -ShowHelp

Console Control Commands

Server Control Commands:
    Ctrl+C   : Gracefully terminate the server.
    Ctrl+R   : Restart the server and reload configurations.
    Ctrl+P   : Suspend the server.
    Ctrl+D   : Disable Server
    Ctrl+H   : Hide Help
    Ctrl+B   : Open the first HTTP endpoint in the default browser.
    ----
    Ctrl+M   : Show Metrics
    Ctrl+E   : Hide Endpoints
    Ctrl+Q   : Hide OpenAPI
    Ctrl+L   : Clear the Console
    Ctrl+Q   : Enable Quiet Mode

Notes

Events like Suspend and Resume provide hooks for additional custom behavior during these transitions.
The Disable-PodeServer and Enable-PodeServer functions offer a lightweight alternative to suspend/resume by controlling only incoming requests, leaving the server's internal state intact.
The improved initialization process ensures that endpoints do not receive input and schedules are not executed until the server is fully initialized, maintaining stability.

…s and Pipeline Support

- Add Clear-PodeKeyPressed to avoid an undeliberate sequence of pressed keys - fix OpenAPI `Show-PodeOAConsoleInfo` that shows openAPi referecente to not http protocols - Solve an issue when the first runspace to stop is not a Main one - DisableTermination disable any key input

Badgerati

Reviewed all the code, just not the docs.

Also, I'm guessing you've edited some of this outside of VSCode? As the auto-formatting in some files seems to have not triggered 🤔

src/Locales/en/Pode.psd1

src/Private/CancellationToken.ps1

src/Private/Console.ps1

Badgerati · 2024-12-17T23:17:35Z

src/Private/Console.ps1

+        $protocolLabel = switch ($protocol) {
+            'HTTP' { 'HTTP      ' }
+            'HTTPS' { 'HTTPS     ' }
+            'WS' { 'WebSocket ' }
+            'SMTP' { 'SMTP      ' }
+            'SMTPS' { 'SMTPS      ' }
+            'TCP' { 'TCP       ' }
+            'TCPS' { 'TCPS      ' }
+            default { 'UNKNOWN   ' }
+        }


Is this necessary, as every endpoint printed is already prepended with the protocol? https:// etc.

It’s looking good 😀

src/Private/Console.ps1

mdaneri · 2024-12-18T01:07:24Z

Not everything in vscode. Multiple instances on different platforms but always in vscode.
I noted that sometimes when opening a C# file, VS code stops to consider PowerShell settings.
It happened more than once time but Im not sure how to reproduce it

I simplified the console flow removing the cancellation token part. new Resolve-PodeCancellationToken to deal with that and changed the main core loop

mdaneri and others added 30 commits November 2, 2024 15:45

Add Enhanced Diagnostic Dump Feature with Configurable Output Format…

7ffe56c

…s and Pipeline Support

add pipe example

8cc7d02

various improvements

6121cb5

Merge branch 'develop' into invoke-podedump

d362833

Fixes and improvements

dbf54d9

Update Helpers.ps1

14afc55

added variables from runspace

34d7b6b

Update Dump.ps1

f05adda

Added suspend and resume server

b64da21

internazioanalization+ example

7db258a

Update PetData.json

88642e8

Documentation

65836b5

upgrade powershell to '7.2.24'

52574f9

Update Server.Tests.ps1

0bd3f8a

Merge branch 'develop' into invoke-podedump

7dd5f96

fixes

6135e17

- Add Clear-PodeKeyPressed to avoid an undeliberate sequence of pressed keys - fix OpenAPI `Show-PodeOAConsoleInfo` that shows openAPi referecente to not http protocols - Solve an issue when the first runspace to stop is not a Main one - DisableTermination disable any key input

Fix CTRL B issue

82a6020

fixes

49f962b

Merge branch 'develop' into invoke-podedump

70a8696

add net9

82c2a28

Merge remote-tracking branch 'upstream/develop' into invoke-podedump

6ec63d9

Merge remote-tracking branch 'upstream/develop' into invoke-podedump

e41c207

doc fixes

f0c8b45

first review

dc76df3

second update

c8ab57c

suspend http and tcp

79fdf46

fix tests

900001a

WSS suspension

526325c

Fix suspend

ce5cc01

Update DebuggerHandler.cs

9cdaf4e

Badgerati requested changes Dec 17, 2024

View reviewed changes

Badgerati assigned mdaneri Dec 17, 2024

Badgerati added the feature ☀️ label Dec 17, 2024

mdaneri added 26 commits December 17, 2024 19:23

first round

aca1440

Revisited DisableTermination , Quiet and DisableConsoleInput

1471532

Introduce a new -Daemon parameter

9a211ee

Add note regarding -Daemon param

edcdf7e

Added new console check for windows

cca932a

Update Context.ps1

cf977ad

set GetStdHandle as private function

3c80605

Native for unix

71bc53c

Update Console.ps1

b07964e

Update Helpers.ps1

ac41815

modified Protect-PodeValue

08d0143

Update Schedules.ps1

cea75d3

Core loop changes

c0e0b0a

I simplified the console flow removing the cancellation token part. new Resolve-PodeCancellationToken to deal with that and changed the main core loop

Replace Server status string with enum

4a8ab97

Update _.Tests.ps1

1742bcb

fix _tests.ps1

f9f4c39

Update Server.Tests.ps1

a4596d9

convert start-sleep to start-podesleep

96defff

improvements

67100c7

add Enable Disable events

856ff30

added PodeServerEventType

fd114ef

fix Server.Tests

1137d65

Added new -ConfigFile param

ef44d0b

fix Helpers test

b44eeaf

rollback Get-PodeRelativePath -NormalisePath

2959759

Update Helpers.Tests.ps1

9518040

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhance Pode Server with Suspend, Resume, and Advanced Console Features #1461

Enhance Pode Server with Suspend, Resume, and Advanced Console Features #1461

mdaneri commented Dec 8, 2024 •

edited

Loading

Badgerati left a comment

Badgerati Dec 17, 2024

mdaneri Dec 18, 2024

mdaneri commented Dec 18, 2024

Enhance Pode Server with Suspend, Resume, and Advanced Console Features #1461

Are you sure you want to change the base?

Enhance Pode Server with Suspend, Resume, and Advanced Console Features #1461

Conversation

mdaneri commented Dec 8, 2024 • edited Loading

Description

Key Features

Use Cases

Example Usage

Console Control Commands

Notes

Badgerati left a comment

Choose a reason for hiding this comment

Badgerati Dec 17, 2024

Choose a reason for hiding this comment

mdaneri Dec 18, 2024

Choose a reason for hiding this comment

mdaneri commented Dec 18, 2024

mdaneri commented Dec 8, 2024 •

edited

Loading