DOCSEARCHbyAlgolia
Submit Docs

Pode

repository·develop·Indexed 21 days ago

https://github.com/badgerati/pode

A web server framework for PowerShell that provides highly configurable console output for monitoring and controlling server activities. It includes a CLI for project initialization via package.json, tools for building from source using Invoke-Build, and advanced debugging capabilities using Wait-PodeDebugger and Out-PodeHost.

Tokens
201.1K
Snippets
635
Records
778
Agent score
77%

What's inside Pode

  1. Overview of Pode features

    develop

    Pode is a cross-platform framework for creating web servers that host REST APIs, Web Sites, and TCP/SMTP Servers. It is built on PowerShell Core (with support for PS5) and supports various deployment environments including Docker (ARM/Raspberry Pi), Azure Functions, AWS Lambda, and IIS.

    Key capabilities include:

    • Protocols: HTTP(S), WS(S), SSE, SMTP(S), and TCP(S).
    • API & Web: REST APIs (OpenAPI 3.0.x/3.1.0), static content with caching, and dynamic rendering via .pode files or third-party template engines.
    • Security: Middleware, sessions (with CSRF and Flash support), authentication (Basic, Windows, Azure AD), authorization (Roles, Groups, Scopes), and IP/subnet allow/deny lists.
    • Performance & Scaling: Multi-thread support, request/response compression (GZip/Deflate), rate limiting, and in-memory caching (with Redis support).
    • Automation: Async timers, cron-based scheduled tasks, and file watchers.
    • Observability: Logging to CLI, files, or custom services like LogStash.
    • Management: Secret management via vaults and server restarts via file monitoring.

  2. Understand OpenAPI v3.0.3 support in Pode

    develop

    Pode provides support for the OpenAPI v3.0.3 Specification, which allows you to define a standard, language-agnostic interface for your RESTful APIs. This enables humans and computers to discover and understand your service's capabilities without access to source code.

    Note on Limitations: Not all OpenAPI features are supported by Pode. Specifically, Relative Schema Document Examples are currently unsupported.

  3. What is Endware and how does it differ from Middleware?

    develop

    Endware is a post-route execution mechanism in Pode. Unlike Middleware, which runs before or during a route, Endware runs after a Route has completed.

    Key characteristics:

    • Guaranteed Execution: Endware runs regardless of whether the prior Middleware or Route logic succeeded or failed (e.g., even if an HTTP 500 or 404 error was thrown).
    • Independence: If multiple Endwares are configured, they are invoked sequentially but independently. If one Endware fails, the subsequent Endwares in the pipeline will still be executed.
    • Built-in Endwares: Pode includes default Endware for Logging and Sessions (to persist session data).

  4. Use Post-Validation logic in Custom Authentication

    develop

    The New-PodeAuthScheme -Custom function accepts an optional -PostValidator ScriptBlock. This script runs after the primary user validation in Add-PodeAuth has succeeded.

    It is useful for secondary checks (e.g., re-generating hashes or checking additional session state). The -PostValidator receives the following parameters in order:

    1. The original array returned from the New-PodeAuthScheme parsing script.
    2. The result HashTable returned from the Add-PodeAuth validator.
    3. The -ArgumentList HashTable passed to New-PodeAuthScheme.

    Crucial: If the post-validation is successful, you must return the user object (the second parameter, often named $result) to complete the authentication process.

    $custom_scheme = New-PodeAuthScheme -Custom -ScriptBlock {
    param($opts)
    return @($WebEvent.Data.user, $WebEvent.Data.pass)
} -PostValidator {
    param($user, $pass, $parsedArray, $result, $opts)

    # Perform extra logic
    # ...

    # You MUST return the result to maintain the authenticated user
    return $result
}

$custom_scheme | Add-PodeAuth -Name 'Login' -ScriptBlock {
    param($user, $pass)
    return @{ User = $user }
}

  5. Configure client Accept-Encoding headers for compression

    develop

    For Pode to perform compression, the client must include an Accept-Encoding header in the request. Pode supports the following encoding methods:

    • gzip
    • deflate

    If the client sends multiple encodings (e.g., gzip,deflate), Pode will use the first supported value. You can also use quality values (q-values) to weight encodings or disable specific ones (e.g., identity;q=0).

    If the client does not provide a supported encoding and identity (no-compression) is disabled, Pode will return a 406 error.

    # Supported Accept-Encoding examples:
Accept-Encoding: gzip
Accept-Encoding: deflate
Accept-Encoding: gzip,deflate
Accept-Encoding: gzip,deflate,identity;q=0

  6. Configure multipart/form-data Request Bodies

    develop

    When using multipart/form-data, a schema is required to define the input parameters. Pode allows you to compose complex multipart requests by nesting properties.

    Default Content-Types for Multipart Parts

    When you don't explicitly specify a content type for a part, Pode uses these defaults:

    • Primitives or Arrays of Primitives: text/plain
    • Complex Objects or Arrays of Complex Objects: application/json
    • Strings with format: binary or format: base64: application/octet-stream
    Set-PodeOARequest -RequestBody  (
  New-PodeOARequestBody -Content (
    New-PodeOAContentMediaType -ContentType 'multipart/form-data' -Content (
      New-PodeOAStringProperty -name 'id' -format 'uuid' |
          New-PodeOAObjectProperty -name 'address' -NoProperties |
          New-PodeOAStringProperty -name 'children' -array |
          New-PodeOASchemaProperty -Name 'addresses' -Reference 'Address' -Array |
          New-PodeOAObjectProperty
      )
    )
 )

  7. Configure Access Rule priority

    develop

    By default, access rules are executed in the order they are created (minimum priority). You can control the execution order using the -Priority parameter in Add-PodeLimitAccessRule.

    • Higher values indicate higher priority.
    • If two rules have the same priority, they are executed in the order they were created.
    Add-PodeLimitAccessRule -Name 'example' -Action Deny -Priority 100 -Component @(
    New-PodeLimitIPComponent -IP '192.0.1.0/16'
)

  8. How Pode handles unsupported PowerShell versions

    develop
    Pode includes a runtime warning mechanism to help maintain environment security. If you run Pode using a PowerShell version that is no longer supported by your current Pode release (e.g., because that PowerShell version has reached EOL), Pode will issue a warning at runtime. This warning advises you of the potential risks and recommends updating to a supported PowerShell version.

  9. Override inbuilt rate limiting logic

    develop

    Because rate limiting is a fixed middleware in the request lifecycle, you can override its behavior by providing your own middleware with the specific name __pode_mw_rate_limit__ using Add-PodeMiddleware. This allows you to implement custom logic that can bypass or modify how requests are allowed or denied.

    Add-PodeMiddleware -Name '__pode_mw_rate_limit__' -ScriptBlock {
    # Custom logic here
    return $true
}

  10. How Session Authentication works in Pode

    develop

    Pode supports Session-based authentication, which allows you to decouple the method of logging in from the requirement of being logged in.

    When a route is protected by a session authenticator (e.g., via Add-PodeAuthSession), Pode checks if a valid session exists on the request. If a session is present, the user is considered authenticated. If no session exists, the user is automatically redirected to the configured -FailureUrl.

    This pattern is particularly useful when you have multiple authentication schemes (like Form, OAuth, etc.). While each scheme handles the initial credential verification, they all create a session object that can be used as a 'shared' authentication method for subsequent requests.

  11. Sign and unsign headers

    develop

    Pode allows you to sign header values to ensure integrity. You can sign a header by providing a -Secret parameter to any of the header functions (Add-PodeHeader, Set-PodeHeader, or Get-PodeHeader).

    When using Get-PodeHeader with a -Secret, the function will attempt to unsign the header value to return the raw, original value.

  12. How Pode works in AWS Lambda

    develop
    When running in a serverless environment like AWS Lambda, Pode operates differently than a standard web server. Instead of a continuous loop, the server logic is executed once, the route logic is parsed, any response is returned, and the server is then disposed. This allows you to leverage Pode's routing, middleware, and authentication features within a single AWS Lambda Function execution.