| | | 1 | | using System.Management.Automation; |
| | | 2 | | using System.Diagnostics.CodeAnalysis; |
| | | 3 | | using Kestrun.Languages; |
| | | 4 | | using Kestrun.Models; |
| | | 5 | | using Kestrun.Runtime; |
| | | 6 | | using Microsoft.AspNetCore.Diagnostics; |
| | | 7 | | |
| | | 8 | | namespace Kestrun.Hosting.Options; |
| | | 9 | | /// <summary> |
| | | 10 | | /// Options for configuring Kestrun-style exception handling middleware. |
| | | 11 | | /// </summary> |
| | | 12 | | public sealed class ExceptionOptions : ExceptionHandlerOptions |
| | | 13 | | { |
| | | 14 | | /// <summary> |
| | | 15 | | /// Optional scripting options (e.g., PowerShell). If present, a script-based handler is used. |
| | | 16 | | /// </summary> |
| | | 17 | | private LanguageOptions? _languageOptions; |
| | | 18 | | |
| | | 19 | | /// <summary> |
| | | 20 | | /// Initializes a new instance of the <see cref="ExceptionOptions"/> class. |
| | | 21 | | /// </summary> |
| | | 22 | | /// <param name="host">The KestrunHost instance associated with these options.</param> |
| | | 23 | | /// <param name="developerExceptionPage">If true, enables the Developer Exception Page middleware with default optio |
| | | 24 | | [SetsRequiredMembers] |
| | 5 | 25 | | public ExceptionOptions(KestrunHost host, bool developerExceptionPage = false) |
| | | 26 | | { |
| | 5 | 27 | | ArgumentNullException.ThrowIfNull(host); |
| | 5 | 28 | | Host = host; |
| | 5 | 29 | | if (developerExceptionPage) |
| | | 30 | | { |
| | 1 | 31 | | DeveloperExceptionPageOptions = new DeveloperExceptionPageOptions(); |
| | | 32 | | } |
| | 5 | 33 | | } |
| | | 34 | | |
| | | 35 | | /// <summary> |
| | | 36 | | /// Optional Developer Exception Page options. If present, the Developer Exception Page middleware is used. |
| | | 37 | | /// </summary> |
| | 7 | 38 | | public DeveloperExceptionPageOptions? DeveloperExceptionPageOptions { get; set; } |
| | | 39 | | |
| | | 40 | | /// <summary> |
| | | 41 | | /// Optional scripting options (e.g., PowerShell). If present, a script-based handler is used. |
| | | 42 | | /// </summary> |
| | | 43 | | public LanguageOptions? LanguageOptions |
| | | 44 | | { |
| | 2 | 45 | | get => _languageOptions; |
| | | 46 | | set |
| | | 47 | | { |
| | 2 | 48 | | _languageOptions = value; |
| | 2 | 49 | | if (value is not null && ExceptionHandler is null) |
| | | 50 | | { |
| | 2 | 51 | | if (value.Language == Scripting.ScriptLanguage.PowerShell) |
| | | 52 | | { |
| | 0 | 53 | | throw new NotSupportedException("PowerShell is not supported for ExceptionOptions scripting at this |
| | | 54 | | } |
| | 2 | 55 | | var compiled = Host.CompileScript(value); |
| | | 56 | | |
| | 2 | 57 | | ExceptionHandler = BuildScriptExceptionHandler(this, compiled); |
| | | 58 | | } |
| | 2 | 59 | | } |
| | | 60 | | } |
| | | 61 | | |
| | | 62 | | /// <summary>Host is needed for runspace/bootstrap if using PowerShell.</summary> |
| | 8 | 63 | | public required KestrunHost Host { get; init; } |
| | | 64 | | |
| | | 65 | | // .NET 8 compatibility: ExceptionHandlerOptions in .NET 8 does not expose StatusCodeSelector. |
| | | 66 | | // Provide our own selector for net8.0; on net9.0+ prefer the base property. |
| | | 67 | | #if !NET9_0_OR_GREATER |
| | | 68 | | /// <summary> |
| | | 69 | | /// .NET 8: Optional custom status code selector for JSON/script fallback. |
| | | 70 | | /// Lets you map exception types to status codes. |
| | | 71 | | /// </summary> |
| | 1 | 72 | | public Func<Exception, int>? LegacyStatusCodeSelector { get; set; } |
| | | 73 | | #endif |
| | | 74 | | |
| | | 75 | | private RequestDelegate BuildScriptExceptionHandler(ExceptionOptions o, RequestDelegate compiled) |
| | | 76 | | { |
| | 2 | 77 | | return async httpContext => |
| | 2 | 78 | | { |
| | 2 | 79 | | // Ensure a PS runspace exists if we're executing a PowerShell-based handler outside the normal PS middlewar |
| | 2 | 80 | | var needsBootstrap = o.LanguageOptions!.Language == Scripting.ScriptLanguage.PowerShell && |
| | 2 | 81 | | !httpContext.Items.ContainsKey(PowerShellDelegateBuilder.PS_INSTANCE_KEY); |
| | 2 | 82 | | |
| | 2 | 83 | | if (!needsBootstrap) |
| | 2 | 84 | | { |
| | 2 | 85 | | await compiled(httpContext); |
| | 2 | 86 | | return; |
| | 2 | 87 | | } |
| | 2 | 88 | | |
| | 0 | 89 | | var pool = o.Host.RunspacePool; // throws if not initialized |
| | 0 | 90 | | var runspace = await pool.AcquireAsync(httpContext.RequestAborted); |
| | 0 | 91 | | using var ps = PowerShell.Create(); |
| | 0 | 92 | | ps.Runspace = runspace; |
| | 2 | 93 | | |
| | 2 | 94 | | // Build Kestrun abstractions and inject for the script to consume |
| | 2 | 95 | | |
| | 0 | 96 | | var kr = new KestrunContext(Host, httpContext); |
| | 0 | 97 | | httpContext.Items[PowerShellDelegateBuilder.PS_INSTANCE_KEY] = ps; |
| | 0 | 98 | | httpContext.Items[PowerShellDelegateBuilder.KR_CONTEXT_KEY] = kr; |
| | 0 | 99 | | ps.Runspace.SessionStateProxy.SetVariable("Context", kr); |
| | 2 | 100 | | |
| | 2 | 101 | | try |
| | 2 | 102 | | { |
| | 0 | 103 | | await compiled(httpContext); |
| | 0 | 104 | | } |
| | 2 | 105 | | finally |
| | 2 | 106 | | { |
| | 0 | 107 | | o.Host.RunspacePool.Release(ps.Runspace); |
| | 0 | 108 | | ps.Dispose(); |
| | 0 | 109 | | _ = httpContext.Items.Remove(PowerShellDelegateBuilder.PS_INSTANCE_KEY); |
| | 0 | 110 | | _ = httpContext.Items.Remove(PowerShellDelegateBuilder.KR_CONTEXT_KEY); |
| | 2 | 111 | | } |
| | 4 | 112 | | }; |
| | | 113 | | } |
| | | 114 | | |
| | | 115 | | /// <summary> |
| | | 116 | | /// Builds a JSON fallback handler that can be used if no script/inline handler is provided. |
| | | 117 | | /// </summary> |
| | | 118 | | /// <param name="useProblemDetails">Whether to use RFC 7807 ProblemDetails in the JSON fallback.</param> |
| | | 119 | | /// <param name="includeDetailsInDevelopment">Whether to include exception details in development.</param> |
| | | 120 | | /// <param name="compress">Whether to compress the JSON response.</param> |
| | | 121 | | /// <returns></returns> |
| | | 122 | | public void UseJsonExceptionHandler(bool useProblemDetails, bool includeDetailsInDevelopment, bool compress = false) |
| | | 123 | | { |
| | 1 | 124 | | ExceptionHandler = async httpContext => |
| | 1 | 125 | | { |
| | 1 | 126 | | // If the response already started, let the server bubble up |
| | 1 | 127 | | if (httpContext.Response.HasStarted) |
| | 1 | 128 | | { |
| | 1 | 129 | | // optional: log here |
| | 0 | 130 | | return; |
| | 1 | 131 | | } |
| | 1 | 132 | | |
| | 1 | 133 | | var env = httpContext.RequestServices.GetService(typeof(IHostEnvironment)) as IHostEnvironment; |
| | 1 | 134 | | var feature = httpContext.Features.Get<IExceptionHandlerFeature>(); |
| | 1 | 135 | | var ex = feature?.Error; |
| | 1 | 136 | | |
| | 1 | 137 | | #if NET9_0_OR_GREATER |
| | 1 | 138 | | var status = StatusCodeSelector?.Invoke(ex ?? new Exception("Unhandled exception")) |
| | 1 | 139 | | ?? StatusCodes.Status500InternalServerError; |
| | 1 | 140 | | #else |
| | 1 | 141 | | var status = LegacyStatusCodeSelector?.Invoke(ex ?? new Exception("Unhandled exception")) |
| | 1 | 142 | | ?? StatusCodes.Status500InternalServerError; |
| | 1 | 143 | | #endif |
| | 1 | 144 | | |
| | 1 | 145 | | var kestrunContext = new KestrunContext(Host, httpContext); |
| | 1 | 146 | | |
| | 1 | 147 | | // Always set the HTTP status first |
| | 1 | 148 | | kestrunContext.Response.StatusCode = status; |
| | 1 | 149 | | |
| | 1 | 150 | | // Choose the right media type |
| | 1 | 151 | | var contentType = useProblemDetails |
| | 1 | 152 | | ? "application/problem+json; charset=utf-8" |
| | 1 | 153 | | : "application/json; charset=utf-8"; |
| | 1 | 154 | | |
| | 1 | 155 | | // No-cache for error payloads |
| | 1 | 156 | | httpContext.Response.Headers.CacheControl = "no-store, no-cache, must-revalidate"; |
| | 1 | 157 | | httpContext.Response.Headers.Pragma = "no-cache"; |
| | 1 | 158 | | httpContext.Response.Headers.Expires = "0"; |
| | 1 | 159 | | |
| | 1 | 160 | | // Build body |
| | 1 | 161 | | var body = new Dictionary<string, object?> |
| | 1 | 162 | | { |
| | 1 | 163 | | ["status"] = status, |
| | 1 | 164 | | ["traceId"] = System.Diagnostics.Activity.Current?.Id ?? httpContext.TraceIdentifier, |
| | 1 | 165 | | ["instance"] = httpContext.Request.Path.HasValue ? httpContext.Request.Path.Value : "/" |
| | 1 | 166 | | }; |
| | 1 | 167 | | |
| | 1 | 168 | | if (useProblemDetails) |
| | 1 | 169 | | { |
| | 1 | 170 | | body["type"] = "about:blank"; // you can swap for a doc URL later |
| | 1 | 171 | | body["title"] = status switch |
| | 1 | 172 | | { |
| | 0 | 173 | | 400 => "Bad Request", |
| | 0 | 174 | | 401 => "Unauthorized", |
| | 0 | 175 | | 403 => "Forbidden", |
| | 0 | 176 | | 404 => "Not Found", |
| | 1 | 177 | | _ => "Internal Server Error" |
| | 1 | 178 | | }; |
| | 1 | 179 | | body["detail"] = includeDetailsInDevelopment && EnvironmentHelper.IsDevelopment() |
| | 1 | 180 | | ? ex?.ToString() |
| | 1 | 181 | | : ex?.Message; |
| | 1 | 182 | | } |
| | 1 | 183 | | else |
| | 1 | 184 | | { |
| | 0 | 185 | | body["error"] = true; |
| | 0 | 186 | | body["message"] = (includeDetailsInDevelopment && EnvironmentHelper.IsDevelopment()) |
| | 0 | 187 | | ? ex?.ToString() |
| | 0 | 188 | | : ex?.Message; |
| | 1 | 189 | | } |
| | 1 | 190 | | |
| | 1 | 191 | | // Note: `compress` means "compact JSON". Pretty-print when not compressing. |
| | 1 | 192 | | // Adjust the `5` (maxDepth) if your WriteJsonResponseAsync uses it that way. |
| | 1 | 193 | | await kestrunContext.Response.WriteJsonResponseAsync( |
| | 1 | 194 | | body, |
| | 1 | 195 | | 5, |
| | 1 | 196 | | compress, // compact when true |
| | 1 | 197 | | status, |
| | 1 | 198 | | contentType |
| | 1 | 199 | | ); |
| | 1 | 200 | | |
| | 1 | 201 | | await kestrunContext.Response.ApplyTo(httpContext.Response); |
| | 2 | 202 | | }; |
| | 1 | 203 | | } |
| | | 204 | | } |