#647

pending completion

Build # #647

Build Type

push

github-actions

Committed by

web-flow

Commit Message

<a href="https://github.com/Badgerati/Pode/commit/<a class=hub.com/Badgerati/Pode/commit/3e7f434ef79f1d320da08e525c32bb4f46b8891d">3e7f434ef<a href="https://github.com/Badgerati/Pode/commit/3e7f434ef79f1d320da08e525c32bb4f46b8891d">">Merge </a><a class="double-link" href="https://github.com/Badgerati/Pode/commit/<a class="double-link" href="https://github.com/Badgerati/Pode/commit/c71ce0324b68927b13360e9d419ee99067d0dfcf">c71ce0324</a>">c71ce0324</a><a href="https://github.com/Badgerati/Pode/commit/3e7f434ef79f1d320da08e525c32bb4f46b8891d"> into b1dacab5d">b1dacab5d</a>

Run Details

39 of 39 new or added lines in 2 files covered. (100.0%)

2714 of 5981 relevant lines covered (45.38%)

1.17 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

33.91

/src/Public/Logging.ps1

<#
.SYNOPSIS
Create a new method of outputting logs.

.DESCRIPTION
Create a new method of outputting logs.

.PARAMETER Terminal
If supplied, will use the inbuilt Terminal logging output method.

.PARAMETER File
If supplied, will use the inbuilt File logging output method.

.PARAMETER Path
The File Path of where to store the logs.

.PARAMETER Name
The File Name to prepend new log files using.

.PARAMETER Batch
An optional batch size to write log items in bulk (Default: 1)

.PARAMETER BatchTimeout
An optional batch timeout, in seconds, to send items off for writing if a log item isn't received (Default: 0)

.PARAMETER MaxDays
The maximum number of days to keep logs, before Pode automatically removes them.

.PARAMETER MaxSize
The maximum size of a log file, before Pode starts writing to a new log file.

.PARAMETER Custom
If supplied, will allow you to create a Custom Logging output method.

.PARAMETER ScriptBlock
The ScriptBlock that defines how to output a log item.

.PARAMETER ArgumentList
An array of arguments to supply to the Custom Logging output method's ScriptBlock.

.EXAMPLE
$term_logging = New-PodeLoggingMethod -Terminal

.EXAMPLE
$file_logging = New-PodeLoggingMethod -File -Path ./logs -Name 'requests'

.EXAMPLE
$custom_logging = New-PodeLoggingMethod -Custom -ScriptBlock { /* logic */ }
#>
function New-PodeLoggingMethod
{
    [CmdletBinding(DefaultParameterSetName='Terminal')]
    [OutputType([hashtable])]
    param (
        [Parameter(ParameterSetName='Terminal')]
        [switch]
        $Terminal,

        [Parameter(ParameterSetName='File')]
        [switch]
        $File,

        [Parameter(ParameterSetName='File')]
        [string]
        $Path = './logs',

        [Parameter(Mandatory=$true, ParameterSetName='File')]
        [string]
        $Name,

        [Parameter()]
        [int]
        $Batch = 1,

        [Parameter()]
        [int]
        $BatchTimeout = 0,

        [Parameter(ParameterSetName='File')]
        [ValidateScript({
            if ($_ -lt 0) {
                throw "MaxDays must be 0 or greater, but got: $($_)s"
            }

            return $true
        })]
        [int]
        $MaxDays = 0,

        [Parameter(ParameterSetName='File')]
        [ValidateScript({
            if ($_ -lt 0) {
                throw "MaxSize must be 0 or greater, but got: $($_)s"
            }

            return $true
        })]
        [int]
        $MaxSize = 0,

        [Parameter(ParameterSetName='Custom')]
        [switch]
        $Custom,

        [Parameter(Mandatory=$true, ParameterSetName='Custom')]
        [ValidateScript({
            if (Test-IsEmpty $_) {
                throw "A non-empty ScriptBlock is required for the Custom logging output method"
            }

            return $true
        })]
        [scriptblock]
        $ScriptBlock,

        [Parameter(ParameterSetName='Custom')]
        [object[]]
        $ArgumentList
    )

    # batch details
    $batchInfo = @{
        Size = $Batch
        Timeout = $BatchTimeout
        LastUpdate = $null
        Items = @()
    }

    # return info on appropriate logging type
    switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {
        'terminal' {
            return @{
                ScriptBlock = (Get-PodeLoggingTerminalMethod)
                Batch = $batchInfo
                Arguments = @{}
            }
        }

        'file' {
            $Path = (Protect-PodeValue -Value $Path -Default './logs')
            $Path = (Get-PodeRelativePath -Path $Path -JoinRoot)
            New-Item -Path $Path -ItemType Directory -Force | Out-Null

            return @{
                ScriptBlock = (Get-PodeLoggingFileMethod)
                Batch = $batchInfo
                Arguments = @{
                    Name = $Name
                    Path = $Path
                    MaxDays = $MaxDays
                    MaxSize = $MaxSize
                    FileId = 0
                    Date = $null
                    NextClearDown = [datetime]::Now.Date
                }
            }
        }

        'custom' {
            return @{
                ScriptBlock = $ScriptBlock
                Batch = $batchInfo
                Arguments = $ArgumentList
            }
        }
    }
}


<#
.SYNOPSIS
Enables Request Logging using a supplied output method.

.DESCRIPTION
Enables Request Logging using a supplied output method.

.PARAMETER Method
The Method to use for output the log entry (From New-PodeLoggingMethod).

.PARAMETER Raw
If supplied, the log item returned will be the raw Request item as a hashtable and not a string (for Custom methods).

.EXAMPLE
New-PodeLoggingMethod -Terminal | Enable-PodeRequestLogging
#>
function Enable-PodeRequestLogging
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $Method,

        [switch]
        $Raw
    )

    Test-PodeIsServerless -FunctionName 'Enable-PodeRequestLogging' -ThrowError

    $name = Get-PodeRequestLoggingName

    # error if it's already enabled
    if ($PodeContext.Server.Logging.Types.Contains($name)) {
        throw 'Request Logging has already been enabled'
    }

    # ensure the Method contains a scriptblock
    if (Test-IsEmpty $Method.ScriptBlock) {
        throw "The supplied output Method for Request Logging requires a valid ScriptBlock"
    }

    # add the request logger
    $PodeContext.Server.Logging.Types[$name] = @{
        Method = $Method
        ScriptBlock = (Get-PodeLoggingInbuiltType -Type Requests)
        Arguments = @{
            Raw = $Raw
        }
    }
}

<#
.SYNOPSIS
Disables Request Logging.

.DESCRIPTION
Disables Request Logging.

.EXAMPLE
Disable-PodeRequestLogging
#>
function Disable-PodeRequestLogging
{
    [CmdletBinding()]
    param()

    Remove-PodeLogger -Name (Get-PodeRequestLoggingName)
}

<#
.SYNOPSIS
Enables Error Logging using a supplied output method.

.DESCRIPTION
Enables Error Logging using a supplied output method.

.PARAMETER Method
The Method to use for output the log entry (From New-PodeLoggingMethod).

.PARAMETER Levels
The Levels of errors that should be logged (default is Error).

.PARAMETER Raw
If supplied, the log item returned will be the raw Error item as a hashtable and not a string (for Custom methods).

.EXAMPLE
New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
#>
function Enable-PodeErrorLogging
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $Method,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [ValidateSet('Error', 'Warning', 'Informational', 'Verbose', 'Debug')]
        [string[]]
        $Levels = @('Error'),

        [switch]
        $Raw
    )

    $name = Get-PodeErrorLoggingName

    # error if it's already enabled
    if ($PodeContext.Server.Logging.Types.Contains($name)) {
        throw 'Error Logging has already been enabled'
    }

    # ensure the Method contains a scriptblock
    if (Test-IsEmpty $Method.ScriptBlock) {
        throw "The supplied output Method for Error Logging requires a valid ScriptBlock"
    }

    # add the error logger
    $PodeContext.Server.Logging.Types[$name] = @{
        Method = $Method
        ScriptBlock = (Get-PodeLoggingInbuiltType -Type Errors)
        Arguments = @{
            Raw = $Raw
            Levels = $Levels
        }
    }
}

<#
.SYNOPSIS
Disables Error Logging.

.DESCRIPTION
Disables Error Logging.

.EXAMPLE
Disable-PodeErrorLogging
#>
function Disable-PodeErrorLogging
{
    [CmdletBinding()]
    param()

    Remove-PodeLogger -Name (Get-PodeErrorLoggingName)
}

<#
.SYNOPSIS
Adds a custom Logging method for parsing custom log items.

.DESCRIPTION
Adds a custom Logging method for parsing custom log items.

.PARAMETER Name
A unique Name for the Logging method.

.PARAMETER Method
The Method to use for output the log entry (From New-PodeLoggingMethod).

.PARAMETER ScriptBlock
The ScriptBlock defining logic that transforms an item, and returns it for outputting.

.PARAMETER ArgumentList
An array of arguments to supply to the Custom Logger's ScriptBlock.

.EXAMPLE
New-PodeLoggingMethod -Terminal | Add-PodeLogger -Name 'Main' -ScriptBlock { /* logic */ }
#>
function Add-PodeLogger
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [string]
        $Name,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [hashtable]
        $Method,

        [Parameter(Mandatory=$true)]
        [ValidateScript({
            if (Test-IsEmpty $_) {
                throw "A non-empty ScriptBlock is required for the logging method"
            }

            return $true
        })]
        [scriptblock]
        $ScriptBlock,

        [Parameter()]
        [object[]]
        $ArgumentList
    )

    # ensure the name doesn't already exist
    if ($PodeContext.Server.Logging.Types.ContainsKey($Name)) {
        throw "Logging method already defined: $($Name)"
    }

    # ensure the Method contains a scriptblock
    if (Test-IsEmpty $Method.ScriptBlock) {
        throw "The supplied output Method for the '$($Name)' Logging method requires a valid ScriptBlock"
    }

    # add logging method to server
    $PodeContext.Server.Logging.Types[$Name] = @{
        Method = $Method
        ScriptBlock = $ScriptBlock
        Arguments = $ArgumentList
    }
}

<#
.SYNOPSIS
Removes a configured Logging method.

.DESCRIPTION
Removes a configured Logging method.

.PARAMETER Name
The Name of the Logging method.

.EXAMPLE
Remove-PodeLogger -Name 'LogName'
#>
function Remove-PodeLogger
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [string]
        $Name
    )

    $PodeContext.Server.Logging.Types.Remove($Name) | Out-Null
}

<#
.SYNOPSIS
Clears all Logging methods that have been configured.

.DESCRIPTION
Clears all Logging methods that have been configured.

.EXAMPLE
Clear-PodeLoggers
#>
function Clear-PodeLoggers
{
    [CmdletBinding()]
    param()

    $PodeContext.Server.Logging.Types.Clear()
}

<#
.SYNOPSIS
Writes and Exception or ErrorRecord using the inbuilt error logging.

.DESCRIPTION
Writes and Exception or ErrorRecord using the inbuilt error logging.

.PARAMETER Exception
An Exception to write.

.PARAMETER ErrorRecord
An ErrorRecord to write.

.PARAMETER Level
The Level of the error being logged.

.PARAMETER CheckInnerException
If supplied, any exceptions are check for inner exceptions. If one is present, this is also logged.

.EXAMPLE
try { /* logic */ } catch { $_ | Write-PodeErrorLog }

.EXAMPLE
[System.Exception]::new('error message') | Write-PodeErrorLog
#>
function Write-PodeErrorLog
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true, ValueFromPipeline=$true, ParameterSetName='Exception')]
        [System.Exception]
        $Exception,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true, ParameterSetName='Error')]
        [System.Management.Automation.ErrorRecord]
        $ErrorRecord,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [ValidateSet('Error', 'Warning', 'Informational', 'Verbose', 'Debug')]
        [string]
        $Level = 'Error',

        [Parameter(ParameterSetName='Exception')]
        [switch]
        $CheckInnerException
    )

    # do nothing if logging is disabled, or error logging isn't setup
    $name = Get-PodeErrorLoggingName
    if (!(Test-PodeLoggerEnabled -Name $name)) {
        return
    }

    # do nothing if the error level isn't present
    $_args = (Get-PodeLogger -Name $name).Arguments
    if (@($_args.Levels) -inotcontains $Level) {
        return
    }

    # build error object for what we need
    switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {
        'exception' {
            $item = @{
                Category = $Exception.Source
                Message = $Exception.Message
                StackTrace = $Exception.StackTrace
            }
        }

        'error' {
            $item = @{
                Category = $ErrorRecord.CategoryInfo.ToString()
                Message = $ErrorRecord.Exception.Message
                StackTrace = $ErrorRecord.ScriptStackTrace
            }
        }
    }

    # add general info
    $item['Server'] = $env:COMPUTERNAME
    $item['Level'] = $Level
    $item['Date'] = [datetime]::Now
    $item['ThreadId'] = [int]$ThreadId

    # add the item to be processed
    $PodeContext.LogsToProcess.Add(@{
        Name = $name
        Item = $item
    }) | Out-Null

    # for exceptions, check the inner exception
    if ($CheckInnerException -and ($null -ne $Exception.InnerException) -and ![string]::IsNullOrWhiteSpace($Exception.InnerException.Message)) {
        $Exception.InnerException | Write-PodeErrorLog
    }
}

<#
.SYNOPSIS
Write an object to a configured custom Logging method.

.DESCRIPTION
Write an object to a configured custom Logging method.

.PARAMETER Name
The Name of the Logging method.

.PARAMETER InputObject
The Object to write.

.EXAMPLE
$object | Write-PodeLog -Name 'LogName'
#>
function Write-PodeLog
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [string]
        $Name,

        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [object]
        $InputObject
    )

    # do nothing if logging is disabled, or logger isn't setup
    if (!(Test-PodeLoggerEnabled -Name $Name)) {
        return
    }

    # add the item to be processed
    $PodeContext.LogsToProcess.Add(@{
        Name = $Name
        Item = $InputObject
    }) | Out-Null
}

<#
.SYNOPSIS
Masks values within a log item to protect sensitive information.

.DESCRIPTION
Masks values within a log item, or any string, to protect sensitive information.
Patterns, and the Mask, can be configured via the server.psd1 configuration file.

.PARAMETER Item
The string Item to mask values.

.EXAMPLE
$value = Protect-PodeLogItem -Item 'Username=Morty, Password=Hunter2'
#>
function Protect-PodeLogItem
{
    [CmdletBinding()]
    param(
        [Parameter(ValueFromPipeline=$true)]
        [string]
        $Item
    )

    # do nothing if there are no masks
    if (Test-IsEmpty $PodeContext.Server.Logging.Masking.Patterns) {
        return $item
    }

    # attempt to apply each mask
    foreach ($mask in $PodeContext.Server.Logging.Masking.Patterns) {
        if ($Item -imatch $mask) {
            # has both keep before/after
            if ($Matches.ContainsKey('keep_before') -and $Matches.ContainsKey('keep_after')) {
                $Item = ($Item -ireplace $mask, "`${keep_before}$($PodeContext.Server.Logging.Masking.Mask)`${keep_after}")
            }

            # has just keep before
            elseif ($Matches.ContainsKey('keep_before')) {
                $Item = ($Item -ireplace $mask, "`${keep_before}$($PodeContext.Server.Logging.Masking.Mask)")
            }

            # has just keep after
            elseif ($Matches.ContainsKey('keep_after')) {
                $Item = ($Item -ireplace $mask, "$($PodeContext.Server.Logging.Masking.Mask)`${keep_after}")
            }

            # normal mask
            else {
                $Item = ($Item -ireplace $mask, $PodeContext.Server.Logging.Masking.Mask)
            }
        }
    }

    return $Item
}

1	<#
2	.SYNOPSIS
3	Create a new method of outputting logs.
4
5	.DESCRIPTION
6	Create a new method of outputting logs.
7
8	.PARAMETER Terminal
9	If supplied, will use the inbuilt Terminal logging output method.
10
11	.PARAMETER File
12	If supplied, will use the inbuilt File logging output method.
13
14	.PARAMETER Path
15	The File Path of where to store the logs.
16
17	.PARAMETER Name
18	The File Name to prepend new log files using.
19
20	.PARAMETER Batch
21	An optional batch size to write log items in bulk (Default: 1)
22
23	.PARAMETER BatchTimeout
24	An optional batch timeout, in seconds, to send items off for writing if a log item isn't received (Default: 0)
25
26	.PARAMETER MaxDays
27	The maximum number of days to keep logs, before Pode automatically removes them.
28
29	.PARAMETER MaxSize
30	The maximum size of a log file, before Pode starts writing to a new log file.
31
32	.PARAMETER Custom
33	If supplied, will allow you to create a Custom Logging output method.
34
35	.PARAMETER ScriptBlock
36	The ScriptBlock that defines how to output a log item.
37
38	.PARAMETER ArgumentList
39	An array of arguments to supply to the Custom Logging output method's ScriptBlock.
40
41	.EXAMPLE
42	$term_logging = New-PodeLoggingMethod -Terminal
43
44	.EXAMPLE
45	$file_logging = New-PodeLoggingMethod -File -Path ./logs -Name 'requests'
46
47	.EXAMPLE
48	$custom_logging = New-PodeLoggingMethod -Custom -ScriptBlock { /* logic */ }
49	#>
50	function New-PodeLoggingMethod
51	{
52	[CmdletBinding(DefaultParameterSetName='Terminal')]
53	[OutputType([hashtable])]
54	param (
55	[Parameter(ParameterSetName='Terminal')]
56	[switch]
57	$Terminal,
58
59	[Parameter(ParameterSetName='File')]
60	[switch]
61	$File,
62
63	[Parameter(ParameterSetName='File')]
64	[string]
65	$Path = './logs',
66
67	[Parameter(Mandatory=$true, ParameterSetName='File')]
68	[string]
69	$Name,
70
71	[Parameter()]
72	[int]
73	$Batch = 1,
74
75	[Parameter()]
76	[int]
77	$BatchTimeout = 0,
78
79	[Parameter(ParameterSetName='File')]
80	[ValidateScript({
81	if ($_ -lt 0) {	×
82	throw "MaxDays must be 0 or greater, but got: $($_)s"	×
83	}
84
85	return $true	×
86	})]
87	[int]
88	$MaxDays = 0,
89
90	[Parameter(ParameterSetName='File')]
91	[ValidateScript({
92	if ($_ -lt 0) {	×
93	throw "MaxSize must be 0 or greater, but got: $($_)s"	×
94	}
95
96	return $true	×
97	})]
98	[int]
99	$MaxSize = 0,
100
101	[Parameter(ParameterSetName='Custom')]
102	[switch]
103	$Custom,
104
105	[Parameter(Mandatory=$true, ParameterSetName='Custom')]
106	[ValidateScript({
107	if (Test-IsEmpty $_) {	×
108	throw "A non-empty ScriptBlock is required for the Custom logging output method"	×
109	}
110
111	return $true	×
112	})]
113	[scriptblock]
114	$ScriptBlock,
115
116	[Parameter(ParameterSetName='Custom')]
117	[object[]]
118	$ArgumentList
119	)
120
121	# batch details
122	$batchInfo = @{	×
123	Size = $Batch	×
124	Timeout = $BatchTimeout	×
125	LastUpdate = $null	×
126	Items = @()	×
127	}
128
129	# return info on appropriate logging type
130	switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {	×
131	'terminal' {
132	return @{	×
133	ScriptBlock = (Get-PodeLoggingTerminalMethod)	×
134	Batch = $batchInfo	×
135	Arguments = @{}	×
136	}
137	}
138
139	'file' {
140	$Path = (Protect-PodeValue -Value $Path -Default './logs')	×
141	$Path = (Get-PodeRelativePath -Path $Path -JoinRoot)	×
142	New-Item -Path $Path -ItemType Directory -Force \| Out-Null	×
143
144	return @{	×
145	ScriptBlock = (Get-PodeLoggingFileMethod)	×
146	Batch = $batchInfo	×
147	Arguments = @{	×
148	Name = $Name	×
149	Path = $Path	×
150	MaxDays = $MaxDays	×
151	MaxSize = $MaxSize	×
152	FileId = 0	×
153	Date = $null	×
154	NextClearDown = [datetime]::Now.Date	×
155	}
156	}
157	}
158
159	'custom' {
160	return @{	×
161	ScriptBlock = $ScriptBlock	×
162	Batch = $batchInfo	×
163	Arguments = $ArgumentList	×
164	}
165	}
166	}
167	}
168
169
170	<#
171	.SYNOPSIS
172	Enables Request Logging using a supplied output method.
173
174	.DESCRIPTION
175	Enables Request Logging using a supplied output method.
176
177	.PARAMETER Method
178	The Method to use for output the log entry (From New-PodeLoggingMethod).
179
180	.PARAMETER Raw
181	If supplied, the log item returned will be the raw Request item as a hashtable and not a string (for Custom methods).
182
183	.EXAMPLE
184	New-PodeLoggingMethod -Terminal \| Enable-PodeRequestLogging
185	#>
186	function Enable-PodeRequestLogging
187	{
188	[CmdletBinding()]
189	param (
190	[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
191	[hashtable]
192	$Method,
193
194	[switch]
195	$Raw
196	)
197
198	Test-PodeIsServerless -FunctionName 'Enable-PodeRequestLogging' -ThrowError	×
199
200	$name = Get-PodeRequestLoggingName	×
201
202	# error if it's already enabled
203	if ($PodeContext.Server.Logging.Types.Contains($name)) {	×
204	throw 'Request Logging has already been enabled'	×
205	}
206
207	# ensure the Method contains a scriptblock
208	if (Test-IsEmpty $Method.ScriptBlock) {	×
209	throw "The supplied output Method for Request Logging requires a valid ScriptBlock"	×
210	}
211
212	# add the request logger
213	$PodeContext.Server.Logging.Types[$name] = @{	×
214	Method = $Method	×
215	ScriptBlock = (Get-PodeLoggingInbuiltType -Type Requests)	×
216	Arguments = @{	×
217	Raw = $Raw	×
218	}
219	}
220	}
221
222	<#
223	.SYNOPSIS
224	Disables Request Logging.
225
226	.DESCRIPTION
227	Disables Request Logging.
228
229	.EXAMPLE
230	Disable-PodeRequestLogging
231	#>
232	function Disable-PodeRequestLogging
233	{
234	[CmdletBinding()]
235	param()
236
237	Remove-PodeLogger -Name (Get-PodeRequestLoggingName)	×
238	}
239
240	<#
241	.SYNOPSIS
242	Enables Error Logging using a supplied output method.
243
244	.DESCRIPTION
245	Enables Error Logging using a supplied output method.
246
247	.PARAMETER Method
248	The Method to use for output the log entry (From New-PodeLoggingMethod).
249
250	.PARAMETER Levels
251	The Levels of errors that should be logged (default is Error).
252
253	.PARAMETER Raw
254	If supplied, the log item returned will be the raw Error item as a hashtable and not a string (for Custom methods).
255
256	.EXAMPLE
257	New-PodeLoggingMethod -Terminal \| Enable-PodeErrorLogging
258	#>
259	function Enable-PodeErrorLogging
260	{
261	[CmdletBinding()]
262	param (
263	[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
264	[hashtable]
265	$Method,
266
267	[Parameter()]
268	[ValidateNotNullOrEmpty()]
269	[ValidateSet('Error', 'Warning', 'Informational', 'Verbose', 'Debug')]
270	[string[]]
271	$Levels = @('Error'),	×
272
273	[switch]
274	$Raw
275	)
276
277	$name = Get-PodeErrorLoggingName	×
278
279	# error if it's already enabled
280	if ($PodeContext.Server.Logging.Types.Contains($name)) {	×
281	throw 'Error Logging has already been enabled'	×
282	}
283
284	# ensure the Method contains a scriptblock
285	if (Test-IsEmpty $Method.ScriptBlock) {	×
286	throw "The supplied output Method for Error Logging requires a valid ScriptBlock"	×
287	}
288
289	# add the error logger
290	$PodeContext.Server.Logging.Types[$name] = @{	×
291	Method = $Method	×
292	ScriptBlock = (Get-PodeLoggingInbuiltType -Type Errors)	×
293	Arguments = @{	×
294	Raw = $Raw	×
295	Levels = $Levels	×
296	}
297	}
298	}
299
300	<#
301	.SYNOPSIS
302	Disables Error Logging.
303
304	.DESCRIPTION
305	Disables Error Logging.
306
307	.EXAMPLE
308	Disable-PodeErrorLogging
309	#>
310	function Disable-PodeErrorLogging
311	{
312	[CmdletBinding()]
313	param()
314
315	Remove-PodeLogger -Name (Get-PodeErrorLoggingName)	×
316	}
317
318	<#
319	.SYNOPSIS
320	Adds a custom Logging method for parsing custom log items.
321
322	.DESCRIPTION
323	Adds a custom Logging method for parsing custom log items.
324
325	.PARAMETER Name
326	A unique Name for the Logging method.
327
328	.PARAMETER Method
329	The Method to use for output the log entry (From New-PodeLoggingMethod).
330
331	.PARAMETER ScriptBlock
332	The ScriptBlock defining logic that transforms an item, and returns it for outputting.
333
334	.PARAMETER ArgumentList
335	An array of arguments to supply to the Custom Logger's ScriptBlock.
336
337	.EXAMPLE
338	New-PodeLoggingMethod -Terminal \| Add-PodeLogger -Name 'Main' -ScriptBlock { /* logic */ }
339	#>
340	function Add-PodeLogger
341	{
342	[CmdletBinding()]
343	param (
344	[Parameter(Mandatory=$true)]
345	[string]
346	$Name,
347
348	[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
349	[hashtable]
350	$Method,
351
352	[Parameter(Mandatory=$true)]
353	[ValidateScript({
354	if (Test-IsEmpty $_) {	×
355	throw "A non-empty ScriptBlock is required for the logging method"	×
356	}
357
358	return $true	×
359	})]
360	[scriptblock]
361	$ScriptBlock,
362
363	[Parameter()]
364	[object[]]
365	$ArgumentList
366	)
367
368	# ensure the name doesn't already exist
369	if ($PodeContext.Server.Logging.Types.ContainsKey($Name)) {	×
370	throw "Logging method already defined: $($Name)"	×
371	}
372
373	# ensure the Method contains a scriptblock
374	if (Test-IsEmpty $Method.ScriptBlock) {	×
375	throw "The supplied output Method for the '$($Name)' Logging method requires a valid ScriptBlock"	×
376	}
377
378	# add logging method to server
379	$PodeContext.Server.Logging.Types[$Name] = @{	×
380	Method = $Method	×
381	ScriptBlock = $ScriptBlock	×
382	Arguments = $ArgumentList	×
383	}
384	}
385
386	<#
387	.SYNOPSIS
388	Removes a configured Logging method.
389
390	.DESCRIPTION
391	Removes a configured Logging method.
392
393	.PARAMETER Name
394	The Name of the Logging method.
395
396	.EXAMPLE
397	Remove-PodeLogger -Name 'LogName'
398	#>
399	function Remove-PodeLogger
400	{
401	[CmdletBinding()]
402	param (
403	[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
404	[string]
405	$Name
406	)
407
408	$PodeContext.Server.Logging.Types.Remove($Name) \| Out-Null	×
409	}
410
411	<#
412	.SYNOPSIS
413	Clears all Logging methods that have been configured.
414
415	.DESCRIPTION
416	Clears all Logging methods that have been configured.
417
418	.EXAMPLE
419	Clear-PodeLoggers
420	#>
421	function Clear-PodeLoggers
422	{
423	[CmdletBinding()]
424	param()
425
426	$PodeContext.Server.Logging.Types.Clear()	×
427	}
428
429	<#
430	.SYNOPSIS
431	Writes and Exception or ErrorRecord using the inbuilt error logging.
432
433	.DESCRIPTION
434	Writes and Exception or ErrorRecord using the inbuilt error logging.
435
436	.PARAMETER Exception
437	An Exception to write.
438
439	.PARAMETER ErrorRecord
440	An ErrorRecord to write.
441
442	.PARAMETER Level
443	The Level of the error being logged.
444
445	.PARAMETER CheckInnerException
446	If supplied, any exceptions are check for inner exceptions. If one is present, this is also logged.
447
448	.EXAMPLE
449	try { /* logic */ } catch { $_ \| Write-PodeErrorLog }
450
451	.EXAMPLE
452	[System.Exception]::new('error message') \| Write-PodeErrorLog
453	#>
454	function Write-PodeErrorLog
455	{
456	[CmdletBinding()]
457	param (
458	[Parameter(Mandatory=$true, ValueFromPipeline=$true, ParameterSetName='Exception')]
459	[System.Exception]
460	$Exception,
461
462	[Parameter(Mandatory=$true, ValueFromPipeline=$true, ParameterSetName='Error')]
463	[System.Management.Automation.ErrorRecord]
464	$ErrorRecord,
465
466	[Parameter()]
467	[ValidateNotNullOrEmpty()]
468	[ValidateSet('Error', 'Warning', 'Informational', 'Verbose', 'Debug')]
469	[string]
470	$Level = 'Error',
471
472	[Parameter(ParameterSetName='Exception')]
473	[switch]
474	$CheckInnerException
475	)
476
477	# do nothing if logging is disabled, or error logging isn't setup
478	$name = Get-PodeErrorLoggingName	2✔
479	if (!(Test-PodeLoggerEnabled -Name $name)) {	4✔
480	return
481	}
482
483	# do nothing if the error level isn't present
484	$_args = (Get-PodeLogger -Name $name).Arguments	4✔
485	if (@($_args.Levels) -inotcontains $Level) {	4✔
486	return
487	}
488
489	# build error object for what we need
490	switch ($PSCmdlet.ParameterSetName.ToLowerInvariant()) {	2✔
491	'exception' {
492	$item = @{	2✔
493	Category = $Exception.Source	2✔
494	Message = $Exception.Message	2✔
495	StackTrace = $Exception.StackTrace	2✔
496	}
497	}
498
499	'error' {
500	$item = @{	2✔
501	Category = $ErrorRecord.CategoryInfo.ToString()	2✔
502	Message = $ErrorRecord.Exception.Message	2✔
503	StackTrace = $ErrorRecord.ScriptStackTrace	2✔
504	}
505	}
506	}
507
508	# add general info
509	$item['Server'] = $env:COMPUTERNAME	2✔
510	$item['Level'] = $Level	2✔
511	$item['Date'] = [datetime]::Now	2✔
512	$item['ThreadId'] = [int]$ThreadId	2✔
513
514	# add the item to be processed
515	$PodeContext.LogsToProcess.Add(@{	2✔
516	Name = $name	2✔
517	Item = $item	2✔
518	}) \| Out-Null	2✔
519
520	# for exceptions, check the inner exception
521	if ($CheckInnerException -and ($null -ne $Exception.InnerException) -and ![string]::IsNullOrWhiteSpace($Exception.InnerException.Message)) {	4✔
522	$Exception.InnerException \| Write-PodeErrorLog	×
523	}
524	}
525
526	<#
527	.SYNOPSIS
528	Write an object to a configured custom Logging method.
529
530	.DESCRIPTION
531	Write an object to a configured custom Logging method.
532
533	.PARAMETER Name
534	The Name of the Logging method.
535
536	.PARAMETER InputObject
537	The Object to write.
538
539	.EXAMPLE
540	$object \| Write-PodeLog -Name 'LogName'
541	#>
542	function Write-PodeLog
543	{
544	[CmdletBinding()]
545	param (
546	[Parameter(Mandatory=$true)]
547	[string]
548	$Name,
549
550	[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
551	[object]
552	$InputObject
553	)
554
555	# do nothing if logging is disabled, or logger isn't setup
556	if (!(Test-PodeLoggerEnabled -Name $Name)) {	4✔
557	return
558	}
559
560	# add the item to be processed
561	$PodeContext.LogsToProcess.Add(@{	2✔
562	Name = $Name	2✔
563	Item = $InputObject	2✔
564	}) \| Out-Null	2✔
565	}
566
567	<#
568	.SYNOPSIS
569	Masks values within a log item to protect sensitive information.
570
571	.DESCRIPTION
572	Masks values within a log item, or any string, to protect sensitive information.
573	Patterns, and the Mask, can be configured via the server.psd1 configuration file.
574
575	.PARAMETER Item
576	The string Item to mask values.
577
578	.EXAMPLE
579	$value = Protect-PodeLogItem -Item 'Username=Morty, Password=Hunter2'
580	#>
581	function Protect-PodeLogItem
582	{
583	[CmdletBinding()]
584	param(
585	[Parameter(ValueFromPipeline=$true)]
586	[string]
587	$Item
588	)
589
590	# do nothing if there are no masks
591	if (Test-IsEmpty $PodeContext.Server.Logging.Masking.Patterns) {	2✔
592	return $item	2✔
593	}
594
595	# attempt to apply each mask
596	foreach ($mask in $PodeContext.Server.Logging.Masking.Patterns) {	2✔
597	if ($Item -imatch $mask) {	2✔
598	# has both keep before/after
599	if ($Matches.ContainsKey('keep_before') -and $Matches.ContainsKey('keep_after')) {	2✔
600	$Item = ($Item -ireplace $mask, "`${keep_before}$($PodeContext.Server.Logging.Masking.Mask)`${keep_after}")	6✔
601	}
602
603	# has just keep before
604	elseif ($Matches.ContainsKey('keep_before')) {	2✔
605	$Item = ($Item -ireplace $mask, "`${keep_before}$($PodeContext.Server.Logging.Masking.Mask)")	6✔
606	}
607
608	# has just keep after
609	elseif ($Matches.ContainsKey('keep_after')) {	2✔
610	$Item = ($Item -ireplace $mask, "$($PodeContext.Server.Logging.Masking.Mask)`${keep_after}")	6✔
611	}
612
613	# normal mask
614	else {
615	$Item = ($Item -ireplace $mask, $PodeContext.Server.Logging.Masking.Mask)	4✔
616	}
617	}
618	}
619
620	return $Item	2✔
621	}

Badgerati / Pode / #647

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous