Private/Resolve-PatServerContext.ps1
|
function Resolve-PatServerContext { <# .SYNOPSIS Resolves server connection context including URI and authentication headers. .DESCRIPTION Centralizes the logic for resolving which Plex server to use and obtaining the appropriate authentication headers. This helper eliminates duplicated boilerplate across cmdlets and provides a consistent pattern for handling both explicit ServerUri parameters and default server configurations. The returned context object includes a WasExplicitUri flag that indicates whether the user explicitly specified a ServerUri. This is critical for internal cmdlet-to-cmdlet calls: when using the default server, child cmdlets should NOT receive ServerUri so they can perform their own default server resolution with proper authentication. .PARAMETER ServerUri Optional URI of the Plex server. If not specified, uses the default stored server. .PARAMETER Token Optional Plex authentication token. Required when using explicit ServerUri to authenticate with the server. If not specified with ServerUri, requests will be unauthenticated and may fail with 401 errors. .OUTPUTS PSCustomObject with properties: - Uri: The effective server URI to use - Headers: Hashtable of HTTP headers including authentication if available - WasExplicitUri: Boolean indicating if ServerUri was explicitly provided - Server: The server configuration object (only when using default server) .EXAMPLE $ctx = Resolve-PatServerContext -ServerUri $ServerUri $response = Invoke-PatApi -Uri $ctx.Uri -Headers $ctx.Headers .EXAMPLE # For internal cmdlet calls, only pass ServerUri if it was explicit: $ctx = Resolve-PatServerContext -ServerUri $ServerUri $params = @{ CollectionId = 123 } if ($ctx.WasExplicitUri) { $params['ServerUri'] = $ctx.Uri } Get-PatCollection @params .NOTES This function throws if no default server is configured and ServerUri is not provided. #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [Parameter(Mandatory = $false)] [string] $ServerUri, [Parameter(Mandatory = $false)] [string] $Token ) if ($ServerUri) { Write-Verbose "Using explicitly specified server: $ServerUri" $headers = @{ Accept = 'application/json' } if (-not [string]::IsNullOrWhiteSpace($Token)) { $headers['X-Plex-Token'] = $Token Write-Debug "Adding X-Plex-Token header for authenticated request" } return [PSCustomObject]@{ Uri = $ServerUri Headers = $headers WasExplicitUri = $true Server = $null Token = $Token } } $server = Get-PatStoredServer -Default -ErrorAction 'Stop' if (-not $server) { throw "No default server configured. Use Add-PatServer with -Default or specify -ServerUri." } Write-Verbose "Using default server: $($server.uri)" return [PSCustomObject]@{ Uri = $server.uri Headers = Get-PatAuthenticationHeader -Server $server WasExplicitUri = $false Server = $server Token = $null # Token retrieved from stored server, not needed for nested calls } } |