Public/Connect-DokuServer.ps1
|
function Connect-DokuServer { <# .SYNOPSIS Connect to a DokuWiki API endpoint .DESCRIPTION Connect to a DokuWiki API endpoint to enable subsequent DokuWiki commands from the same PowerShell session .PARAMETER ComputerName The computer name (single label or FQDN) / IP to connect to .PARAMETER Credential The credentials used to authenticate to the API endpoint .PARAMETER Unencrypted Specify that the APi endpoint is at a http rather than https address. Recommended for development only!! .PARAMETER ApiPath The web path that the api executable is at. DokuWiki default is /lib/exe/xmlrpc.php .PARAMETER Force Force a connection even if one is already established to the same endpoint .EXAMPLE PS C:\> Connect-DokuServer -ComputerName wiki.example.com -Credential (Get-Credential) .OUTPUTS Nothing .NOTES AndyDLP - 2019 .LINK https://github.com/AndyDLP/PSDokuWiki #> [CmdletBinding(PositionalBinding = $true)] param ( [Parameter(Mandatory = $true, Position = 1, HelpMessage = 'The server to connect to')] [ValidateNotNullOrEmpty()] [Alias('Server')] [string]$ComputerName, [Parameter(Mandatory = $true, Position = 2, HelpMessage = 'The credentials to use to connect')] [ValidateNotNullOrEmpty()] [pscredential]$Credential, [Parameter(Mandatory = $false, Position = 3, HelpMessage = 'Connect to an unencrypted endpoint')] [ValidateNotNullOrEmpty()] [switch]$Unencrypted, [Parameter(Mandatory = $false, Position = 4, HelpMessage = 'The path to the api endpoint')] [ValidateNotNullOrEmpty()] [string]$APIPath = '/lib/exe/xmlrpc.php', [Parameter(Mandatory = $false, Position = 5, HelpMessage = 'Force a re-connection')] [ValidateNotNullOrEmpty()] [switch]$Force ) begin {} process { $headers = @{ "Content-Type" = "text/xml"; } $Protocol = if ($Unencrypted) { "http" } else { "https" } $TargetUri = ($Protocol + "://" + $ComputerName + $APIPath) # Check if already connected if (($null -ne $Script:DokuServer) -and (-not $Force)) { throw "Open connection already exists to: $($Script:DokuServer.TargetUri) - Use the -Force parameter to connect anyway" } $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Credential.Password) $password = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR) $XMLPayload = ConvertTo-XmlRpcMethodCall -Name "dokuwiki.login" -Params @($Credential.username, $password) # $Websession var defined here try { $httpResponse = Invoke-WebRequest -Uri $TargetUri -Method Post -Headers $headers -Body $XMLPayload -SessionVariable WebSession -ErrorAction Stop $XMLContent = [xml]($httpResponse.Content) } catch [System.Management.Automation.PSInvalidCastException] { Write-Verbose "Connected to API endpoint: $($Script:DokuServer.TargetUri) but did not receive valid response" $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( ("XML payload sent to: $TargetUri but received an invalid response"), 'DokuWiki.Session.InvalidResponse', [System.Management.Automation.ErrorCategory]::InvalidResult, $TargetUri ) ) } catch [System.Net.WebException] { $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( ("Failed to send POST request to $TargetUri"), 'DokuWiki.Session.InvalidRequest', [System.Management.Automation.ErrorCategory]::InvalidOperation, $TargetUri ) ) } catch { Write-Error "Unspecified error caught in Connect-DokuServer" throw $_ exit } if ($null -ne ($XMLContent | Select-Xml -XPath "//fault").node) { # connected but API failed Write-Error "Connected to API endpoint: $ComputerName, but failed login. FaultCode: $(($XMLContent | Select-Xml -XPath '//struct').node.member[0].value.int) - FaultString: $(($XMLContent | Select-Xml -XPath '//struct').node.member[1].value.string)" $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( ("FaultCode: $(($XMLContent | Select-Xml -XPath '//struct').node.member[0].value.int) - FaultString: $(($XMLContent | Select-Xml -XPath '//struct').node.member[1].value.string)"), 'DokuWiki.Session.FailedLogin', [System.Management.Automation.ErrorCategory]::AuthenticationError, $TargetUri ) ) } elseif ($null -eq ($XMLContent | Select-Xml -XPath "//methodResponse").node) { # not connected / invalid response Write-Verbose "Connected to API endpoint: $($Script:DokuServer.TargetUri) but did not receive valid response" $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( ("XML payload sent to: $TargetUri but received an invalid response"), 'DokuWiki.Session.InvalidResponse', [System.Management.Automation.ErrorCategory]::InvalidResult, $TargetUri ) ) } else { # success Write-Verbose "Successfully connected to API server: $ComputerName" $DokuSession = New-Object PSObject -Property @{ Server = $ComputerName TargetUri = $TargetUri SessionMethod = $SessionMethod Headers = $headers WebSession = $WebSession TimeStamp = (Get-Date) UnencryptedEndpoint = [boolean]$Unencrypted } $DokuSession.PSTypeNames.Insert(0,'DokuWiki.Session.Detail') # Module scoped variables are defined like the below apparently $Script:DokuServer = $DokuSession } } # process end {} } |